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

primParams.h

00001 /************************************************************************************
00002  * primParams.h
00003  *
00004  *  synopsis: Defines primitive ids which are used to index the array of pointers to
00005  *           primitive functions, structure tags for primitive data and reply data,
00006  *           and prototypes of primitive functions.
00007  *
00008  *  related files:
00009  *   listManager.c: Routines which manage the execution of a primitive list and
00010  *                 writing the reply data.
00011  *   primFuncts.c: Contains primitive execution functions common to the master and the
00012  *                slaves and the function which initializes the primParameters array
00013  *                of structures.
00014  *   masterPrimFuncts.c/slavePrimFuncts.c: Contain primitive execution functions
00015  *                specific to the master/slave DSP.
00016  *   primFuncts.h: Declares the structure tag which communicates necessary information
00017  *                to primitive functions.
00018  *
00019  *  Damon Fasching, UW Madison                            fasching@wisconsin.cern.ch
00020  *  Douglas Ferguson, UW Madison   (510) 486-5230         dpferguson@lbl.gov
00021  *
00022  *  modifications/bugs
00023  *   - Split the primitive IDs into 3 sets, so that future primitives can
00024  *     be placed in the appropriate section (common/slave/master) without
00025  *     affecting the already existing primitive lists on the host machines.
00026  *     Currently primitives must be added to the end of the entire list to
00027  *     avoid ID changes of existing primitives & thus re-writes of the
00028  *     primitive lists. Updated the example.                         10.04.02 dpsf
00029  *   - Moved rodConfiguration #defines to rodConfiguration.h, where
00030  *     they belong.                                                  11.04.02 dpsf
00031  *
00032  ************************************************************************************/
00033 #ifndef PRIM_PARAMS
00034 #define PRIM_PARAMS
00035 
00036 #include "processor.h"
00037 #include "utilities.h"
00038 #include "serialStreams.h"
00039 #include "bocStructure.h"
00040 #include "sctStructure.h"
00041 
00042 #if (defined(I_AM_MASTER_DSP) || defined(I_AM_SLAVE_DSP))
00043     #include "primFuncts.h"
00044 #endif
00045 
00046 /*************************************************************************************
00047  *                                     GENERAL
00048  *************************************************************************************
00049  *
00050  * Primitive lists sent from one CPU to another and reply lists returned from the
00051  * recipient CPU have a 3 parts:
00052  *      list header:  tagged by the structure MSG_LIST_HEAD declared in msgBuff.h
00053  *      list body:    composed of the list of primitive or reply messages
00054  *      list trailer: tagged by the structure MSG_LIST_TAIL declared in msgBuff.h
00055  *
00056  * The primitive and reply messages in the list body have 2 parts:
00057  *      message header: tagged by the structure MSG_HEAD declared in msgBuff.h
00058  *      message body:   (optional) primitive specific data.  If there is primitive
00059  *                     specific data, there should be a structure tag for it defined
00060  *                     in primParams.h (this file).  There should be separate tags for
00061  *                     input and/or output data as needed.
00062  *
00063  * The primitive functions themselves never see the listHeader, listBody or msgHeader.
00064  * These structures are interpreted by the interface routines, readListWrapper() and
00065  * execPrim() in listManager.c.  Because of this, changes in the common structures do
00066  * not require changes to any of the primitive functions, only to one or the other of
00067  * the interface routines.  This reduces effort but more importantly reduces the
00068  * possibility of errors.
00069  *
00070  * On receipt of a new primitive list, readListWrapper() extracts the information from
00071  * the list header and the list trailer and checks it for errors.  This information
00072  * guides the execution of the list.
00073  *
00074  * execPrim() is called once for each primitive in a primitive list.  execPrim()
00075  * extracts the information from the message header, checks it for errors and branches
00076  * to the appropriate primitive function.  Primitive functions are all of type INT32
00077  * and have a single argument, a pointer to a structure of type PRIM_DATA declared in
00078  * primFuncts.h.  execPrim() fills the PRIM_DATA structure before branching to the
00079  * primitive function.
00080  *
00081  * All primitive functions receive a pointer to struct PRIM_DATA as an argument.
00082  * There will be many authors of primitives, so it is important that the use of this
00083  * structure is clear.  The structure is described in detail here, followed by
00084  * instructions of how to add a primitive, with an example.
00085  *
00086  *************************************************************************************
00087  *                          The PRIM_DATA data structure
00088  *************************************************************************************
00089  *
00090  * PRIM_DATA is a 5 element structure which is passed to each primitive function. It
00091  * is the sole argument passed to the primitive functions and is filled for all
00092  * primitives by the function execPrim() in listManager.c.  It's use by a primitive
00093  * function may be tricky so requires care!  In particular, 2 of the elements in
00094  * PRIM_DATA are themselves pointers to structures defined by the author of each
00095  * primitive.  These are priBodyPtr and repBodyPtr which point to data used by the
00096  * primitive and returned from the primitive, respectively.  The structures tags which
00097  * describe this data are defined by the primitive authors in this file (primParams.h).
00098  * The elements of PRIM_DATA are now described:
00099  *
00100  * UINT32 *priBodyPtr - This is a pointer to the (optional) message body.  As
00101  * described above, the message body contains primitive specific data which should be
00102  * described by a structure whose tag is in this file (primParams.h).  The executable
00103  * on the CPU which sent the primitive list is also built with primParams.h and so
00104  * uses the same structures to build the primitives.  This ensures that the data
00105  * described by the structure in primParams.h is what the primitive function receives.
00106  *
00107  * UINT32 priBodyLength - This is the number of 4 byte words in the primitive body.
00108  * This may not always be the same for a given primitive if, for example, one of the
00109  * primitive data structure elements is of variable length, as in the example below.
00110  *
00111  * UINT32 *repBodyPtr - This is a pointer to the (optional) message body of the reply
00112  * data.  If there is reply data from the primitive, this pointer tells the primitive
00113  * function where it should put that data.  Again, the author of the primitive is
00114  * responsible to define a structure tag to describe this data.  That tag should also
00115  * be in this file (primParams.h).
00116  *
00117  * UINT32 repBodyLength - This is the number of 4 byte words in the reply message body.
00118  * It should NOT include the reply message header, tagged by MSG_HEAD, which is added
00119  * by execPrim() and which the primitive function knows nothing about.  execPrim()
00120  * initializes repBodyLength to 0; the primitive function does not need to set it to 0
00121  * if there is no reply data.
00122  *
00123  * UINT32 *repBuffEnd - This points to the last valid address where a primitive can
00124  * write reply data.  The primitive function can use this to check that the bounds of
00125  * the reply buffer are not exceeded.  The error code MSG_EXCEEDS_LIST_BOUND can be
00126  * returned if the reply message has been truncated.  The interface routine, execPrim(),
00127  * also checks that a primitive has not not exceeded the boundaries of the reply buffer.
00128  *
00129  * The interface routines do not look at the input data, they just pass a pointer to
00130  * the data. So just as the primitive routines are not affected by changes in the
00131  * common structures, the interface routines are not affected by changes to primitive
00132  * functions and the associated data structures.  This division means that only people
00133  * familiar with a particular piece of code ever have to edit it, and it limits the
00134  * amount of code which is affected by changes.  This all reduces the likelihood of
00135  * introducing bugs when making such changes.
00136  *
00137  *************************************************************************************
00138  *          readListWrapper(), execPrim() and CPU to CPU consistency checks
00139  *************************************************************************************
00140  *
00141  * Each primitive has up to five items defined in this header file:
00142  *
00143  *      ID                            (required)
00144  *      revision number               (required)
00145  *      structure tag for input data  (required if there is input data)
00146  *      structure tag for output data (required if there is reply data)
00147  *      legal values of parameters    (recommended if there are illegal values)
00148  *
00149  * Primitive functions are called from the interface function, execPrim(), based on
00150  * the primitive ID, which is an element of the MSG_HEAD structure.  The executables
00151  * on both the sending and receiving CPUs are built with this header file.  The CPU
00152  * which builds and sends the primitive loads ID into MSG_HEAD to communicate which
00153  * primitives are to be executed.  The CPU which receives the primitive list extracts
00154  * ID from MSG_HEAD and branches to a primitive functions based on ID.
00155  *
00156  * The branching is done by execPrim().  Within execPrim() the primitive ID is used
00157  * as an index of an array of structures which has one array element per primitive.
00158  * The structure tag, PRIM_PARAMETERS, is defined in primFuncts.h.  It has 2 elements:
00159  *
00160  * struct PRIM_PARAMETERS {
00161  *    INT32 (*primFunction)(struct PRIM_DATA *);
00162  *    INT32 primRevision;
00163  * };
00164  *
00165  * primFunction is a pointer to the primitive function.  primRevision is the current
00166  * revision of the primitive.  This is needed to ensure the executables of the sending
00167  * and receiving CPUs were built with the same version.
00168  *
00169  * Because primitive IDs index an array of pointers to primitive functions, they
00170  * must be sequential.  Defining the IDs according to the model below, e.g.
00171  *
00172  * #define ECHO              0
00173  * #define MEMORY_TEST       (1 + (ECHO))
00174  * #define SET_ERRMSG_MASK   (1 + (MEMORY_TEST))
00175  *
00176  * etc. ensures that the primitive IDs are sequential.
00177  *
00178  * Note: The primitive IDs have been divided into 3 sets: common to both master & slave
00179  * DSPs, slave only, master only. New primitives belonging to a given set should be
00180  * placed at the end of the set, so that the previously written primitive lists
00181  * stored on the host computers still remain valid. They are still ordered sequentially
00182  * within the sets to simplify the listManager code. (Table lookups in execPrim,
00183  * checkPrimHeader and initializePrimParams translate the IDs into indices).
00184  *
00185  * The revision number is intended to ensure that both CPUs, sender and receiver,
00186  * are using the same version of a primitive.  In particular, there could be problems
00187  * if the definition of the input data structure or the output data structure is not
00188  * the same on both CPUs.  The primitive revision is an element, primRevision, of the
00189  * MSG_HEAD structure which is filled by the sending CPU.  The receiving CPU checks
00190  * the transmitted version of primRevision in the message header with its local copy
00191  * in the PRIM_PARAMETERS structure and aborts with an error message if there is a
00192  * mismatch. This check is performed in a single place, in the interface routine
00193  * execPrim() in listManager.c.  It should NOT be performed by the primitive
00194  * functions.  In fact, execPrim() does not pass the revision number to the primitive.
00195  *
00196  * There are no restrictions on the mnemonic constants which are used to define the
00197  * ID, the revision and the structure tags for the input and output data of the
00198  * primitive functions.  However, because these constants will be used not only by the
00199  * author of the primitive but also by the authors of code which builds primitive
00200  * lists, there should be some consistency in how they are defined.  The following
00201  * model has been used so far:
00202  *    The ID should indicate what the primitive does.
00203  *    The revision should be the ID preceded by R_ and should be of the form xxyy
00204  *   where xx is the major revision number and yy is the minor revision number.
00205  *    The input structure tag should be the ID appended with _IN
00206  *    The output structure tag should be the ID appended with _OUT.
00207  * For example say we have primitive which sorts the input data and returns this as
00208  * output data and that this primitive follows a primitive with ID ECHO in the list.
00209  * We would have:
00210  * #define SORT_DATA    (1 + (ECHO))            ID is mnemonic and sequential
00211  * #define R_SORT_DATA           300            revision number 3.00
00212  *    struct SORT_DATA_IN {                     structure tag for input data
00213  *      char *unsorted;
00214  *    };
00215  *    struct SORT_DATA_OUT {                    structure tag for output data
00216  *      char *sorted;
00217  *    };
00218  *
00219  * In some cases, it may also be useful to define mnemonics for legal values of
00220  * parameters which are passed in the structures.  See, e.g., SET_LED below.
00221  *
00222  * Finally, the constant PRIM_LIST_REVISION, below, is intended to ensure that the
00223  * primitives which are defined on both CPUs are the same and in the same order, i.e.
00224  * a given ID number corresponds to the same primitive on both sides.
00225  * PRIM_LIST_REVISION should be incremented in the following situations:
00226  *
00227  * 1) A primitive is added to this file.
00228  * 2) A primitive is removed from this file.
00229  * 3) The primitives in this file are reordered.
00230  * *) It does NOT need to be incremented in the event that individual primitives are
00231  *    revised. PRIM_REVISION takes care of that.
00232  *
00233  * The primitive list and the reply list have a common header structure which is tagged
00234  * by MSG_LIST_HEAD in msgBuff.h.  This structure has an element, primListRevision,
00235  * which the sending CPU fills with its copy of PRIM_LIST_REVISION.  The receiving CPU
00236  * checks this against its copy of PRIM_LIST_REVISION and aborts if there is a
00237  * mismatch.  This check is performed in a single place, in the interface routine
00238  * readListWrapper() in listManager.c.
00239  *
00240  *************************************************************************************
00241  *          primitive function skeletons with and without return data
00242  *************************************************************************************
00243  *
00244  * -- SIZEOF(x) is defined as sizeof(x) >> 2, i.e. it is the size in 32 bit words.
00245  * -- In some cases there might not be a structure for the return data, e.g. if it
00246  * -- it's format or size is not completely specified.  In those cases, the last
00247  * -- line would be primData->repBodyLength = N; where N is the size in 32 bit words.
00248  *    see, e.g., rwFifo in masterPrimFuncts.c.
00249  *
00250  * INT32 noReturnDataSkel(struct PRIM_DATA *primData) {
00251  *
00252  *   INT32 returnCode = SUCCESS;
00253  *
00254  *   struct NO_RETURN_DATA_SKEL_IN *noReturnDataSkelIn =
00255  *                     (struct NO_RETURN_DATA_SKEL_IN *)primData->priBodyPtr;
00256  *
00257  *   -- code goes here --
00258  *
00259  *   return returnCode;
00260  * }
00261  *
00262  ***
00263  *
00264  * INT32 returnDataSkel(struct PRIM_DATA *primData) {
00265  *
00266  *   INT32 returnCode = SUCCESS;
00267  *
00268  *   struct RETURN_DATA_SKEL_IN *returnDataSkelIn =
00269  *                     (struct RETURN_DATA_SKEL_IN *)primData->priBodyPtr;
00270  *   struct RETURN_DATA_SKEL_OUT *returnDataSkelOut =
00271  *                     (struct RETURN_DATA_SKEL_OUT *)primData->repBodyPtr;
00272  *
00273  *   -- code goes here --
00274  *
00275  *   primData->repBodyLength = SIZEOF(struct RETURN_DATA_SKEL_OUT);
00276  *
00277  *   return returnCode;
00278  * }
00279  *
00280  * Note that the last line of code which assigns repBodyLength may take other forms.
00281  * For example the echo primitive (in primFuncts.c) has in the body an arbitrary
00282  * number of data words given by priBodyLength and pointed to by priBodyPtr both
00283  * members of the PRIM_DATA structure.  The return message will have the same number
00284  * of words in its body and they will be placed at repBodyPtr, also a member of the
00285  * PRIM_DATA structure.  So there we do not have a structure indicating where the
00286  * primitive and reply data are or their sizes.  repBodyLength is assigned by the line
00287  *   primData->repBodyLength = primData->priBodyLength.
00288  * Other examples of this type of exception are in the rwFifo() in masterPrimFuncts.c
00289  * and in the sortData example below.
00290  *
00291  * Note also that in noReturnDataSkel, it was not necessary to set repBodyLength to
00292  * 0.  This is done in the interface routine, execPrim(), from which all primitives
00293  * are called.
00294  *
00295  *
00296  *
00297  *************************************************************************************
00298  *                                  EXAMPLES
00299  *                   How to add a primitive in 5 easy steps.
00300  *************************************************************************************
00301  *
00302  * Here, the procedure to add a primitive function, checkBit(), is described.
00303  * checkBit() checks whether a bit in a register is set. The result is returned in a
00304  * reply message. checkBit is a primitive common to both types of DSPs, so it is
00305  * placed at the end of the common section.
00306  *
00307  *  1) In primParams.h, define the constant mnemonic for the primitive ID, the
00308  *     revision number and structure tags for the input and output (reply) data.
00309  *
00310  *    #define CHECK_BIT (1 + (<previously last primitive>))
00311  *    #define R_CHECK_BIT   100
00312  *       struct CHECK_BIT_IN {
00313  *         UINT32 registerId;
00314  *         UINT32 bitNumber;
00315  *       };
00316  *       struct CHECK_BIT_OUT {
00317  *         UINT32 bitSet;
00318  *       };
00319  *
00320  *    #define LAST_COMMON_PRIMITIVE         (CHECK_BIT)
00321  *
00322  *  2) In primParams.h, near the bottom, add the prototype for the primitive function.
00323  *
00324  *    INT32 checkBit(struct PRIM_DATA *);
00325  *
00326  *  3) In primParams.h increment PRIM_LIST_REVISION.
00327  *
00328  *  4) Update primIDList & the primParameters array inside initializePrimParams in
00329  *     primFuncts.c; add in the new primitive in the appropriate spot (bottom
00330  *     of common, slave-only, or master-only functions):
00331  *
00332  *     primIDList[++primLoop]=                  CHECK_BIT;
00333  *     primParameters[primLoop].primFunction=   checkBit;
00334  *     primParameters[primLoop].primRevision=   R_CHECK_BIT;
00335  *
00336  *  5) In primFuncts.c, slavePrimFuncts.c or masterPrimFuncts.c, write the routine...
00337  *
00338  *    INT32 checkBit(struct PRIM_DATA *primData) {
00339  *
00340  *      INT32 returnCode = SUCCESS;
00341  *      INT32 error;
00342  *      UINT32 registerId;
00343  *      UINT32 bitNumber;
00344  *      UINT32 bitSet;
00345  *
00346  *      struct CHECK_BIT_IN *checkBitIn =
00347  *                        (struct CHECK_BIT_IN *)primData->priBodyPtr;
00348  *      struct CHECK_BIT_OUT *checkBitOut =
00349  *                        (struct CHECK_BIT_OUT *)primData->repBodyPtr;
00350  *
00351  *      registerId = checkBitIn->registerId;
00352  *      bitNumber = checkBitIn->bitNumber;
00353  *
00354  *      error = readRegister( registerId, 1, bitNumber, &bitSet);
00355  *
00356  *      if (error < 0) {
00357  *        addError(&returnCode,error, "checkBit","readRegister", __FILE__, __LINE__);
00358  *        if (FATAL(returnCode)) { return returnCode; }
00359  *      }
00360  *
00361  *      checkBitOut->bitSet = bitSet;
00362  *      primData->repBodyLength = SIZEOF(struct CHECK_BIT_OUT);
00363  *
00364  *      return returnCode;
00365  *    }
00366  *
00367  *  (Note how an error return from a function call is handled.)
00368  *
00369  * Now we add a primitive function, sortData(), just after checkBit(). sortData sorts
00370  * input byte data and returns the sorted list. Like checkBit, sortData has both input
00371  * and output data. However, neither the input nor the output data has an associated
00372  * structure.  They are after all just unstructured data lists of unspecified length.
00373  *
00374  *  1) In primParams.h, define the constant mnemonic for the primitive ID and the
00375  *    revision number. In this case there are no structure tags.
00376  *
00377  *    #define SORT_DATA (1 + (CHECK_BIT))
00378  *    #define R_SORT_DATA   100
00379  *
00380  *    #define LAST_COMMON_PRIMITIVE         (SORT_DATA)
00381  *
00382  *  2) In primParams.h, near the bottom, add the prototype for the primitive function.
00383  *
00384  *    INT32 sortData(struct PRIM_DATA *);
00385  *
00386  *  3) In primParams.h increment PRIM_LIST_REVISION.
00387  *
00388  *  4) Update primIDList & the primParameters array inside initializePrimParams:
00389  *
00390  *     primIDList[++primLoop]=                  SORT_DATA;
00391  *     primParameters[primLoop].primFunction=   sortData;
00392  *     primParameters[primLoop].primRevision=   R_SORT_DATA;
00393  *
00394  *  5) In primFuncts.c, slavePrimFuncts.c or masterPrimFuncts.c, write the routine...
00395  *
00396  *    INT32 sortData(struct PRIM_DATA *primData) {
00397  *
00398  *      INT32 returnCode = SUCCESS;
00399  *      char *inPtr, *outPtr;
00400  *      char tmp;
00401  *      UINT32 numElements, outer, inner;
00402  *
00403  *      inPtr  = primData->priBodyPtr;
00404  *      outPtr  = primData->repBodyPtr;
00405  *      numElements = 4 * primData->priBodyLength;
00406  *
00407  *      if ((UINT32)inPtr + numElements > (UINT32)primData->repBuffEnd) {
00408  *        newError(&returnCode, MSG_EXCEEDS_LIST_BOUND, FATAL_ERR, "sortData",
00409  *                 "reply data will exceed reply buffer boundary...aborting",
00410  *                 __FILE__, __LINE__);
00411  *        return returnCode;
00412  *      }
00413  *
00414  *      for (outer = 0; outer < (numElements - 2); ++outer) {
00415  *        for (inner = 0; inner < (numElements - 2 - outer); ++inner) {
00416  *          if ( *(inPtr + (char *)inner) > *(inPtr + (char *)(inner+1))) {
00417  *            tmp = *(inPtr + (char *)inner);
00418  *            *(inPtr + (char *)inner) = *(inPtr + (char *)(inner+1));
00419  *            *(inPtr + (char *)(inner+1)) = tmp;
00420  *          }
00421  *        }
00422  *        *(outPtr + (char *)(numElements-1-outer)) =
00423  *                      *(inPtr + (char *)(numElements-1-outer));
00424  *      }
00425  *      *outPtr = *inPtr;
00426  *
00427  *      primData->repBodyLength = primData->priBodyLength;
00428  *
00429  *      return returnCode;
00430  *    }
00431  *
00432  * Note that here a check has been added to make sure the reply data does not exceed
00433  * the reply data buffer.
00434  *
00435  *                                                        D Fasching
00436  */
00437 #define PRIM_LIST_REVISION     111
00438 
00439 
00440 
00441 
00442 
00443 /************************************************************************************
00444  *                        Primitives common to all DSPs go here
00445  * Note: some of these primitives (eventTrapSetup, triggerMask, setTrigger) are used
00446  * to coordinate the DSPs with each other or other electronics on the ROD (such as
00447  * the router). These primitives should be sent to the master DSP from the host; the
00448  * master DSP primitive will then set the appropriate board registers, etc. and pass
00449  * on the primitive to the slave DSP. The primitive passing software will not break
00450  * if the host sends one of these primitives directly to a slave, but slave
00451  * applications might break as a result of inconsistent parameter settings.
00452  ************************************************************************************/
00453 #define COMMON_PRIMITIVES_BASE 0x0
00454 
00455 /* Echo the primitive message body back in the reply message body. */
00456 #define ECHO                    (COMMON_PRIMITIVES_BASE)
00457 #define R_ECHO                  100
00458 /* echo's input & output data is unstructured. */
00459 
00460 /*
00461  * Set error severity mask - levels which are masked will not write an error message
00462  * to the text buffer.
00463  *  IN: errMsgMask: value to set errMsgMask to;
00464  *                  DEFAULT means do not change the value
00465  *  OUT: errMsgMaskOut->errMsgMask: value of errMsgMask at end of this routine
00466  */
00467 #define SET_ERRMSG_MASK         (1 + (ECHO))
00468 #define R_SET_ERRMSG_MASK       100
00469     struct SET_ERRMSG_MASK_IN {
00470         UINT32 errMsgMask;
00471     };
00472     struct SET_ERRMSG_MASK_OUT {
00473         UINT32 errMsgMask;
00474     };
00475 
00476 /*
00477  * Pause the execution of the primitive list.  List execution will resume when the
00478  * RESUME bit is set in the command register.
00479  */
00480 #define PAUSE_LIST              (1 + (SET_ERRMSG_MASK))
00481 #define R_PAUSE_LIST            100
00482 
00483 /* eventTrapSetup:
00484  * Sets the event trapping parameters for a particular slave.  They need to be set
00485  * in the slave DSP and in the router fpga. Common to Master/Slave, however
00486  * eventTrapSetup is intended to be a HOST to MASTER DSP primitive only; the master
00487  * DSP then sets up the router registers and passes a primitive list to call
00488  * eventTrapSetup on the slave DSP.  Trap configuation is not independent, if only
00489  * one trap is used, it must be trap 0. The primary purpose for trap 1 is to have
00490  * a way of running short immediate tasks with a different function (like trapping
00491  * events) on the DSP, while it continues a task such as occupancy counting.
00492  */
00493 #define EVENT_TRAP_SETUP        (1 + (PAUSE_LIST))
00494 #define R_EVENT_TRAP_SETUP      103
00495     struct EVENT_TRAP_SETUP_IN {
00496         UINT32 slvBits, numberOfEvents, timeoutInUsec;
00497         UINT32 extRouterSetup, distribute;
00498         UINT32 releaseFrames, permitBackPressure, dataMode, sLink,
00499                format, trapStray,  iterLimit;
00500         UINT32 trapConfig[2], trapExclusionFlag[2], trapFunction[2],
00501                trapMatch[2],  trapModulus[2],       trapRemainder[2];
00502     };
00503     struct EVENT_TRAP_SETUP_OUT {
00504         UINT32 errorCode;
00505     };
00506     #define  COLLECT_FOREVER  0
00507     #define  KEEP_EVENTS      0
00508 
00509     #define  TRAP_DISTRIB_PRIMARY    0
00510     #define  TRAP_DISTRIB_SECONDARY  1
00511     #define  TRAP_DISTRIB_BOTH       2
00512     #define  TRAP_DISTRIB_NEITHER    3
00513 
00514     #define  TRAP_FMT_NORMAL  0
00515     #define  TRAP_FMT_ERROR   1
00516 
00517     #define  TRAP_CFG_IDLE        0
00518     #define  TRAP_CFG_ATLAS_EVT   1
00519     #define  TRAP_CFG_TIM_EVT     2
00520     #define  TRAP_CFG_ROD_EVT     3
00521     #define  TRAP_CFG_SLINK_EVT   4
00522 
00523     #define  TRAP_FXN_HISTOGRAM   1
00524     #define  TRAP_FXN_TRAP        2
00525     #define  TRAP_FXN_OCCUPANCY   4
00526     #define  TRAP_FXN_ERRORCNT    8
00527     #define  TRAP_FXN_RESYNCH     16
00528 
00529 /* Quickly set a section of the DSP's memory */
00530 #define SET_MEMORY           (1 + (EVENT_TRAP_SETUP))
00531 #define R_SET_MEMORY         100
00532     struct SET_MEMORY_IN {
00533         UINT32 *start, size, val;
00534     };
00535 
00536 /* Quickly copy one section of the DSP's memory into another section */
00537 #define COPY_MEMORY          (1 + (SET_MEMORY))
00538 #define R_COPY_MEMORY        100
00539     struct COPY_MEMORY_IN {
00540         UINT32 *source, *destination, size;
00541     };
00542 
00543 /* New memory test, designed to work with full code (ie not the memory-test mode) */
00544 #define MEMORY_TEST          (1 + (COPY_MEMORY))
00545 #define R_MEMORY_TEST        102
00546     struct MEMORY_TEST_IN {
00547         UINT32 *start, size, repetitions[6], errorsBeforeFail, continueOnError;
00548         UINT32 nReads, dmaFlag;
00549     };
00550     struct MEMORY_TEST_OUT {
00551         UINT32 returnCode;
00552     };
00553 
00554 /* Turn an LED on or off. */
00555 #define SET_LED              (1 + (MEMORY_TEST))
00556 #define R_SET_LED            103
00557     struct SET_LED_IN {
00558         UINT32  ledNum, ledState, toggle;
00559     };
00560     #define YELLOW_LED 0
00561     #define GREEN_LED  1
00562     #define RED_LED    2
00563 
00564     #define OFF     0
00565     #define ON      1
00566     #define TOGGLE  2
00567 
00568 /* Flash an LED.  Period and number of flashes are settable parameters. */
00569 #define FLASH_LED            (1 + (SET_LED))
00570 #define R_FLASH_LED          103
00571     struct FLASH_LED_IN {
00572         UINT32 ledNum, period, numTimes;
00573     };
00574 
00575 #define SEND_DATA            (1 + (FLASH_LED))
00576 #define R_SEND_DATA          102
00577     struct SEND_DATA_IN {
00578         UINT32 dataType, auxVal, repBufferFlag, timeout;
00579     };
00580     struct SEND_DATA_OUT {
00581         UINT32 *dataPtr, dataLength;
00582     };
00583     #define MIRROR_DATA    0x10
00584     #define ROUTER_DATA    0x11
00585     #define STREAM_DATA    0x12
00586 
00587     #define EVENT_DATA     0x20
00588     #define HISTOGRAM_DATA 0x21
00589     #define OCCUPANCY_DATA 0x22
00590     #define FIT_DATA       0x23
00591 
00592 /* setTrigger simply sends the appropriate commands to set & send the trigger;
00593    moduleMask controls which modules receive it. The passOn flag signals whether
00594    the module info should be sent on to the slave DSPs. Like eventTrapSetup,
00595    moduleMask is meant to be sent from the host to the master DSP, which will
00596    transfer its data to the slave DSP(s) if desired. */
00597 #define MODULE_MASK         (1 + (SEND_DATA))
00598 #define R_MODULE_MASK       100
00599     struct MODULE_MASK_IN {
00600         UINT32 moduleMask[2][2], passOn, slv;   /* for command stream 0 & 1 */
00601     };
00602 
00603 /* Send a trigger to the detector electronics. If setTrigger is issued to a
00604    slave DSP, the trigger source is assumed as external (possibly not even issued
00605    by the master DSP); in this case only the current bin & histogram set are set. */
00606 #define N_CMD_LIST_CMDS   6
00607 struct CmdList {
00608     UINT16  cmd[N_CMD_LIST_CMDS];
00609     UINT32 data[N_CMD_LIST_CMDS];
00610 };
00611 
00612 #define SET_TRIGGER          (1 + (MODULE_MASK))
00613 #define R_SET_TRIGGER        102
00614     struct SET_TRIGGER_IN {
00615         struct  CmdList cmdList[2];
00616         UINT32  slvBits;
00617         UINT16  cmdBuff, preBuilt;
00618         UINT32  chipAddress, bin, set;
00619         UINT32  repetitions, interval;
00620         UINT32  preBuiltDataOffset[2];
00621         UINT16  incCmd[2];
00622         UINT32  incData[2];
00623 
00624     };
00625     /* command buffer can be either 0, 1, or both. cmdTypes are defined in
00626        sctStructure.h; not all types listed there are supported. */
00627     #define CMD_BUFFER_0     0
00628     #define CMD_BUFFER_1     1
00629     #define CMD_BUFFER_BOTH  2
00630 
00631 #define START_TASK           (1 + (SET_TRIGGER))
00632 #define R_START_TASK         101
00633     /* Task revision numbers must be updated whenever a task's input parameters
00634        are modified. Revision numbers of the tasks should not exceed 0xff. If
00635        a task has a default position for its memory base (eg. trapTask), that is
00636        defined inside memoryPartitions.h along with the other memory-related
00637        constants. */
00638 
00639     /* master */
00640 /* Task which controls an entire histogram scan */
00641     #define R_HISTOGRAM_CTRL_TASK   107
00642 
00643         struct XPair {
00644             FLOAT32 x0, delta_x;
00645         };
00646         struct RangeList {
00647             struct XPair xPair[5]; 
00648         };
00649         
00650         struct  HISTOGRAM_CTRL_TASK_IN {
00651         UINT8   slvBits, port, configRegister[2];
00652 
00653         UINT8   configSctSet, dataSet;
00654         UINT8   groupRangeMap[2];
00655 
00656         UINT8   groupDSPMap[4];
00657 
00658         UINT8   groupSPMap[2];
00659         UINT8   globalCtrl, syncLevel;
00660 
00661         UINT32  *histoBase;
00662 
00663         UINT8   arrangement, dataFormat, binSize, unused1;
00664         UINT8   extSetup, dataPath, capture, useRangeList /* unused2 */;
00665 
00666         UINT32  repetitions, nBins, bin0;
00667 
00668         struct  RangeList rangeList[2];
00669         FLOAT32 *dataPtr[2];
00670 
00671         struct  CmdList triggerSequence[2];
00672         UINT8   incCmd[2];
00673         UINT8   calLineLoop;
00674         UINT8   distributionToggle;
00675 
00676         UINT32  incData[2];
00677 
00678         UINT32  genData[10];
00679     };
00680 
00681     #define MODULE_BASIC  0
00682     #define MODULE_TRIM   1
00683     #define MODULE_ALL    2
00684 
00685     #define EXT_SETUP_NONE    0
00686     #define EXT_SETUP_ROUTER  1
00687     #define EXT_SETUP_RRIF    2 
00688     #define EXT_SETUP_HISTO   4 
00689 
00690     #define DATA_PATH_NORMAL  0
00691     #define DATA_PATH_INMEM   1
00692 
00693     #define MODULE_GROUP   0
00694     #define ROUTER_DISTRIB 1
00695 
00696     #define SYNC_NEWBIN    0
00697     #define SYNC_TOTAL     1
00698 
00699     struct HISTOGRAM_CTRL_TASK_OUT {
00700         UINT32  totalTime;
00701         UINT32  slvProcTime[4];
00702         UINT32  *dataPtr, dataLength;
00703     };
00704 
00705     #define R_MIRROR_TASK     101
00706     struct MIRROR_TASK_IN {
00707         UINT32 slvBits, mirrorFreq, *mirrorBase,
00708                *mirrorSlvBase, mirrorLen;
00709     };
00710     #define MIRROR_DEFAULT_BASE 0x800000a0
00711 
00712     #define R_TRAP_REQ_TASK   101
00713     struct TRAP_REQ_TASK_IN {
00714         UINT32 slvBits, watchFreq;
00715     };
00716 
00717     /* slave */
00718     #define R_HISTOGRAM_TASK  100
00719     struct HISTOGRAM_TASK_IN {
00720         UINT32 nEvents, controlFlag;  /* nEvents can equal COLLECT_FOREVER too. */
00721     };
00722     /* control flag settings: */
00723     #define MASTER_HREG     0
00724     #define LOCAL_INC       1
00725     #define LOCAL_SET_TRIG  2
00726 
00727     struct HISTOGRAM_TASK_OUT {
00728         UINT32  nEvents, binsDone;
00729         FLOAT32 avgProcTime;
00730         UINT32  *dataPtr, dataLength;
00731     };
00732 
00733     #define R_TRAP_TASK       100
00734     struct TRAP_TASK_IN {
00735         UINT32 nEvents, reloadInterval, trapType, eventType,
00736                *trapBufferBase, trapBufferLength;
00737     };
00738 
00739     struct TRAP_TASK_OUT {
00740         UINT32  nEvents, dataLen;
00741         UINT32  *bufferBase, bufferLen;
00742     };
00743 
00744     #define R_OCCUPANCY_TASK  100
00745     struct OCCUPANCY_TASK_IN {
00746         UINT32 nEvents, nFilters, splitFlag;
00747         char   filter[16];
00748     };
00749 
00750     #define R_ERROR_TASK      100
00751     struct ERROR_TASK_IN {
00752         UINT32 errorType;
00753     };
00754     struct ERROR_TASK_OUT {
00755         UINT32 nErrors;
00756     };
00757 
00758     #define R_RESYNCH_TASK    100
00759     struct RESYNCH_TASK_IN {
00760         UINT32 errorType;
00761     };
00762 
00763     /* tasks can have their own specialized output structures, this is a
00764        general one. It is stored as an array of external structures in
00765        the task manager, so that if a task completes & later the data is
00766        requested, it can be supplied. */
00767     struct GEN_TASK_OUT {
00768         UINT32 *dataPtr, dataLength;
00769     };
00770     union TASK_STRUCTURES_OUT {
00771         struct HISTOGRAM_CTRL_TASK_OUT  histoCtrlTaskOut;
00772         struct HISTOGRAM_TASK_OUT       histogramTaskOut;
00773         struct TRAP_TASK_OUT            trapTaskOut;
00774         struct ERROR_TASK_OUT           errorTaskOut;
00775         struct GEN_TASK_OUT             genTaskOut;
00776     };
00777 
00778     /* MAX_NUM_TASKS is the maximum of the two task numbers for master &
00779        slave DSPs. Bad Things can happen if it is not kept up to date */
00780     #define MAX_NUM_TASKS   5
00781 
00782     /* The IDs of the two task sets cannot not exceed 0xff, and must increment by 1. */
00783     /* master DSP tasks: */
00784     #define MASTER_TASK_BASE     (0x10)
00785     #define HISTOGRAM_CTRL_TASK  (MASTER_TASK_BASE)
00786     #define MIRROR_TASK          (1+(HISTOGRAM_CTRL_TASK))
00787     #define TRAP_REQ_TASK        (1+(MIRROR_TASK))
00788 
00789     #define LAST_MASTER_TASK  (TRAP_REQ_TASK)
00790     #define NUM_MASTER_TASKS  ((LAST_MASTER_TASK)-(MASTER_TASK_BASE)+1)
00791             #define ALL_SLAVES      5
00792 
00793     /* slave DSP tasks: */
00794     #define SLAVE_TASK_BASE  (0x20)
00795     #define HISTOGRAM_TASK  (SLAVE_TASK_BASE)
00796     #define TRAP_TASK       (1+(HISTOGRAM_TASK))
00797     #define OCCUPANCY_TASK  (1+(TRAP_TASK))
00798     #define ERROR_TASK      (1+(OCCUPANCY_TASK))
00799     #define RESYNCH_TASK    (1+(ERROR_TASK))
00800 
00801     #define LAST_SLAVE_TASK  (RESYNCH_TASK)
00802     #define NUM_SLAVE_TASKS  ((LAST_SLAVE_TASK)-(SLAVE_TASK_BASE)+1)
00803 
00804     #if   defined(I_AM_MASTER_DSP)
00805         #define LAST_TASK  (LAST_MASTER_TASK)
00806         #define NUM_TASKS  (NUM_MASTER_TASKS)
00807         #define TASK_BASE  (MASTER_TASK_BASE)
00808     #elif defined(I_AM_SLAVE_DSP)
00809         #define LAST_TASK  (LAST_SLAVE_TASK)
00810         #define NUM_TASKS  (NUM_SLAVE_TASKS)
00811         #define TASK_BASE  (SLAVE_TASK_BASE)
00812     #endif
00813 
00814     union TASK_STRUCTURES_IN {
00815         struct HISTOGRAM_CTRL_TASK_IN  histoCtrlTaskIn;
00816         struct MIRROR_TASK_IN          mirrorMemoryTaskIn;
00817         struct TRAP_REQ_TASK_IN        trapRequestTaskIn;
00818 
00819         struct HISTOGRAM_TASK_IN  histogramTaskIn;
00820         struct TRAP_TASK_IN       trapTaskIn;
00821         struct OCCUPANCY_TASK_IN  occupancyTaskIn;
00822         struct ERROR_TASK_IN      errorTaskIn;
00823         struct RESYNCH_TASK_IN    resynchTaskIn;
00824     };
00825 
00826     struct START_TASK_IN {
00827         UINT32 taskType, taskRevision, priority, completionFlag;
00828         union  TASK_STRUCTURES_IN  taskStruct;
00829     };
00830 
00831 #define TASK_OPERATION      (1 + (START_TASK))
00832 #define R_TASK_OPERATION         100
00833     struct TASK_OPERATION_IN {
00834         UINT32 taskType, taskOperation, data;
00835     };
00836 
00837 #define TASK_STOP         0
00838 #define TASK_PAUSE        1
00839 #define TASK_RESUME       2
00840 #define TASK_QUERY        3
00841 #define TASK_RESET        4
00842 #define TASK_SETPRIORITY  5
00843 
00844 #define TEST         (1 + (TASK_OPERATION))
00845 #define R_TEST              100
00846     struct TEST_IN {
00847         UINT32 dataLen, *dataPtr;
00848     };
00849 
00850 #define WRITE_BUFFER         (1 + (TEST))
00851 #define R_WRITE_BUFFER         101
00852     struct WRITE_BUFFER_IN {
00853         UINT32 buffer;
00854         /*char string[64];*/
00855         char string[2396];  /* sizeof(union PRIM_PARAMS_UNION) => 2400 bytes. */
00856 
00857     };
00858     #define WRITE_BUFFER_ERR  0
00859     #define WRITE_BUFFER_INFO 1
00860     #define WRITE_BUFFER_DIAG 2
00861     #define WRITE_BUFFER_XFER 3
00862 
00863 #define LAST_COMMON_PRIMITIVE   (WRITE_BUFFER)
00864 #define NUM_COMMON_PRIMITIVES   ((LAST_COMMON_PRIMITIVE)-(COMMON_PRIMITIVES_BASE)+1)
00865 
00866 #if   defined(SCT_ROD)
00867     #define COMMON_SCT_PRIMITIVES_BASE 0x800
00868 
00869 /*  //#define XXX (COMMON_SCT_PRIMITIVES_BASE)
00870     //#define LAST_COMMON_SCT_PRIMITIVE   (XXX)
00871     //#define NUM_COMMON_SCT_PRIMITIVES   \
00872     //  ((LAST_COMMON_SCT_PRIMITIVE)-(COMMON_SCT_PRIMITIVES_BASE)+1) */
00873 
00874     #define NUM_COMMON_SCT_PRIMITIVES  0
00875 
00876 #elif defined(PIXEL_ROD)
00877     #define COMMON_PIXEL_PRIMITIVES_BASE 0x800
00878 
00879 /*  //#define XXX (COMMON_PIXEL_PRIMITIVES_BASE)
00880     //#define LAST_COMMON_PIXEL_PRIMITIVE   (XXX)
00881     //#define NUM_COMMON_PIXEL_PRIMITIVES   \
00882     //  ((LAST_COMMON_PIXEL_PRIMITIVE)-(COMMON_PIXEL_PRIMITIVES_BASE)+1) */
00883 
00884     #define NUM_COMMON_PIXEL_PRIMITIVES  0
00885 
00886 #endif
00887 
00888 /************************************************************************************
00889  *                             Slave DSP primitives go here.
00890  ************************************************************************************/
00891 #define SLAVE_PRIMITIVES_BASE  0x1000
00892 
00893 #define START_EVENT_TRAPPING   (SLAVE_PRIMITIVES_BASE)
00894 #define R_START_EVENT_TRAPPING       101
00895 
00896 #define STOP_EVENT_TRAPPING    (1 + (START_EVENT_TRAPPING))
00897 #define R_STOP_EVENT_TRAPPING        100
00898 
00899 /* Set up & define the histograms. */
00900 #define HISTOGRAM_SETUP        (1 + (STOP_EVENT_TRAPPING))
00901 #define R_HISTOGRAM_SETUP            104
00902     struct HISTOGRAM_SETUP_IN {
00903         UINT32  *base, rodType, nBins;
00904         UINT8   padding[2];
00905         UINT8   dataType[2];
00906         UINT8   arrangement, dataFormat, binSize , unused;
00907         UINT32  validModules[2];
00908         UINT32  moduleRangeMap[2][2];
00909         FLOAT32 *xPtr[2];
00910     };
00911     struct HISTOGRAM_SETUP_OUT {
00912         UINT32 *ctrlBase, *pulseCtrBase;
00913     };
00914 
00915 /*
00916     struct HISTOGRAM_SETUP_IN {
00917         UINT32  *base, rodType, nBins;
00918         UINT8   padding[2];
00919         UINT8   dataType[2];
00920         UINT8   calLine, arrangement, dataFormat, binSize;
00921         UINT32  validModules[2];
00922         FLOAT32 *xPtr[2];
00923     };
00924 */
00925     /* The default histogram base is defined inside memoryPartitions.h along with
00926        the other memory-related constants. */
00927     #define ROD_TYPE_SCT     0
00928     #define ROD_TYPE_PIXEL   1
00929 
00930     #define HISTOGRAM_BLOCK    0
00931     #define HISTOGRAM_SLICE    1
00932 
00933     #define HISTOGRAM_CONDENSED 1
00934     #define HISTOGRAM_FULL      3
00935 
00936     #define HISTOGRAM_16BIT     16
00937     #define HISTOGRAM_32BIT     32
00938 
00939 #define LAST_SLAVE_PRIMITIVE    (HISTOGRAM_SETUP)
00940 #define NUM_SLAVE_PRIMITIVES   ((LAST_SLAVE_PRIMITIVE)-(SLAVE_PRIMITIVES_BASE)+1)
00941 
00942 #if   defined(SCT_ROD)
00943     #define SLAVE_SCT_PRIMITIVES_BASE 0x1800
00944 
00945 /*  //#define XXX (SLAVE_SCT_PRIMITIVES_BASE)
00946     //#define LAST_SLAVE_SCT_PRIMITIVE   (XXX)
00947     //#define NUM_SLAVE_SCT_PRIMITIVES   \
00948     //  ((LAST_SLAVE_SCT_PRIMITIVE)-(SLAVE_SCT_PRIMITIVES_BASE)+1) */
00949 
00950     #define NUM_SLAVE_SCT_PRIMITIVES  0
00951 
00952 #elif defined(PIXEL_ROD)
00953     #define SLAVE_PIXEL_PRIMITIVES_BASE 0x1800
00954 
00955 /*  //#define XXX (SLAVE_PIXEL_PRIMITIVES_BASE)
00956     //#define LAST_SLAVE_PIXEL_PRIMITIVE   (XXX)
00957     //#define NUM_SLAVE_PIXEL_PRIMITIVES   \
00958     //  ((LAST_SLAVE_PIXEL_PRIMITIVE)-(SLAVE_PIXEL_PRIMITIVES_BASE)+1) */
00959 
00960     #define NUM_SLAVE_PIXEL_PRIMITIVES  0
00961 
00962 #endif
00963 
00964 /************************************************************************************
00965  *                          Master DSP primitives go here.
00966  ************************************************************************************/
00967 #define MASTER_PRIMITIVES_BASE 0x2000
00968 
00969 /* Read or write a block of slave memory.
00970  * - slaveNumber: ID of slave to be accessed
00971  * - readNotWrite = 0 for writing to slaves, != 0 for reading from slaves
00972  * - *slaveAddress: slave reads: source address of the data
00973  *                  slave writes: destination address of the data
00974  * - *masterAddress: slave reads: destination address of the data; the special value
00975  *                                DEFAULT puts the data in the body of the reply msg
00976  *                                just after the RW_SLAVE_MEMORY_OUT structure
00977  *                   slave writes: source address of the data; the special value
00978  *                                DEFAULT gets the data from the body of the primitive
00979  *                                just after the RW_SLAVE_MEMORY_IN structure
00980  * - numWords: in input structure: number of 32 bit words to read or write */
00981 #define RW_SLAVE_MEMORY         (MASTER_PRIMITIVES_BASE)
00982 #define R_RW_SLAVE_MEMORY       100
00983     struct RW_SLAVE_MEMORY_IN {
00984         UINT32 slaveNumber;
00985         UINT32 readNotWrite;
00986         UINT32 *slaveAddress;   /* DEFAULT address defined above */
00987         UINT32 *masterAddress;  /* DEFAULT address defined above */
00988         UINT32 numWords;
00989     };
00990 
00991 /* Transmit serial data to controller FPGA */
00992 #define TRANS_SERIAL_DATA (1+(RW_SLAVE_MEMORY))
00993 #define R_TRANS_SERIAL_DATA 100
00994     struct TRANS_DATA {
00995         UINT32 port0Data; /* 32b serial data port 0 */
00996         UINT32 port1Data; /* 32b serial data port 1 */
00997     };
00998     struct TRANS_SERIAL_DATA_IN {
00999         UINT32   captureSerOn;      /* Capture module return data in input FIFOs */
01000         UINT32   streamLen[2], *streams;   /* data sets to transmit */
01001     };
01002 
01003 /* Set DSPINT to start slave. */
01004 #define START_SLAVE_EXECUTING     (1 + (TRANS_SERIAL_DATA))
01005 #define R_START_SLAVE_EXECUTING   104
01006     struct START_SLAVE_EXECUTING_IN {
01007         UINT32 slaveNumber;
01008         UINT32 commOnOff;
01009         UINT32 slaveType;
01010         UINT32 timeoutInUsec;
01011     };
01012     struct START_SLAVE_EXECUTING_OUT {
01013         UINT32 slaveNumber;
01014     };
01015     /* commOnOff options */
01016     #define SLV_DSP_COMM_OFF      0
01017     #define SLV_DSP_COMM_ON       1
01018     /* slaveType options */
01019     #define SLV_DSP_UNCONFIGURED  0
01020     #define SLAVE_CALIBRATE       1
01021     #define SLAVE_MONITOR         2
01022     #define SLAVE_ERROR_CHECK     3
01023     #define SLAVE_MEMORY_TEST     4
01024 
01025 /* Sets the parameters of the structure rodConfig.slvDspConfig[slvId]. */
01026 #define CONFIG_SLAVE            (1 + (START_SLAVE_EXECUTING))
01027 #define R_CONFIG_SLAVE          102
01028     struct CONFIG_SLAVE_IN {
01029         UINT32 slaveNumber;
01030         UINT32 commOnOff;
01031         UINT32 slaveType;
01032     };  /* parameters values are same as for START_SLAVE_EXECUTING */
01033 
01034 /*
01035  *  Reads or writes a field of a register in the master DSP memory map.
01036  * registerID: ID of the register being polled
01037  * offset: number of lsb in the field, starting with 0
01038  * width: width of the field
01039  *    mnemonic symbols for registerID, offset and width are in registerIndices.h
01040  * readNotWrite: 1 for read, 0 for write
01041  * dataIn: data to write for readNotWrite = 0; no significance for readNotWrite = 1
01042  * dataOut: data read for readNotWrite = 1; no significance for readNotWrite = 0
01043  */
01044 #define RW_REG_FIELD                 (1 + (CONFIG_SLAVE))
01045 #define R_RW_REG_FIELD               103
01046     struct RW_REG_FIELD_IN {
01047         UINT32 registerID;
01048         UINT32 offset;
01049         UINT32 width;
01050         UINT32 readNotWrite;
01051         UINT32 dataIn;
01052     };
01053     struct RW_REG_FIELD_OUT {
01054         UINT32 dataOut;
01055     };
01056 
01057 /*
01058  *  Polls a field of a register for a value.  A timeout is available.
01059  * registerID: ID of the register being polled
01060  * offset: number of lsb in the field, starting with 0
01061  * width: width of the field
01062  *    mnemonic symbols for registerID, offset and width are in registerIndices.h
01063  * desiredValue: value of the defined field to poll for
01064  * timeoutInUsec: timeout period in microseconds
01065  * found: indicates whether 'desiredValue' was found within 'timeoutInUsec'
01066  */
01067 #define POLL_REG_FIELD               (1 + (RW_REG_FIELD))
01068 #define R_POLL_REG_FIELD             103
01069     struct POLL_REG_FIELD_IN {
01070         UINT32 registerID;
01071         UINT32 offset;
01072         UINT32 width;
01073         UINT32 desiredValue;
01074         UINT32 timeoutInUsec;
01075     };
01076     struct POLL_REG_FIELD_OUT {
01077         UINT32 found;
01078     };
01079 
01080 /* Reads/writes some number of words from/to one of the FIFOs on the ROD.
01081  * - fifoID: INPUT_MEM, DEBUG_MEM or EVENT_MEM
01082  * - bank: BANK_A, BANK_B or (EVENT_MEM only) BANK_C
01083  * - readNotWrite: 1 for read, 0 for write
01084  * - numElements: number of fifo entries to read or write; NOTE: no packing, eg
01085  *              to write 20 elements to INPUT_MEM BANK_A requires 40 32b data words
01086  *              to write 20 elements to EVENT_MEM BANK_C requires 20 32b data words
01087  *              20 elements read from EVENT_MEM BANK_C will occupy 20 32b data words
01088  * - *dataBaseAdr: for readNotWrite = 0 source address of data for the FIFO
01089  *                                = 1 destination address for data from the FIFO
01090  *   if *dataBaseAdr = DEFAULT
01091  *     readNotWrite = 0: data is supplied with the RW_FIFO primitive after *data
01092  *     readNotWrite = 1: data is written to the reply message body after bytesXfrd
01093  *   There is also a scratch space in SDRAM at SCRATCH_BASE (memoryPartitions.h)
01094  * - bytesXfrd: Number of bytes read or written
01095  */
01096 #define RW_FIFO                   (1 + (POLL_REG_FIELD))
01097 #define R_RW_FIFO                 104
01098     struct RW_FIFO_IN {
01099         UINT32 fifoId;
01100         UINT32 bank;
01101         UINT32 readNotWrite;
01102         UINT32 numElements;
01103         UINT32 *dataBaseAdr;    /* DEFAULT value defined above */
01104     };
01105     struct RW_FIFO_OUT {
01106         UINT32 bytesXfrd;
01107     };
01108     #define INPUT_MEM 0x0             /* values of fifoID */
01109     #define DEBUG_MEM 0x1
01110     #define EVENT_MEM 0x2
01111     #define TIM_MEM   0x3
01112     #define BANK_A    0x0             /* values of bank; ignored for TIM_MEM */
01113     #define BANK_B    0x1
01114     #define BANK_C    0x2             /* EVENT_MEM only */
01115 
01116 /*
01117  *  Send a primitive list to a slave DSP.
01118  * slaveNumber: ID of slave DSP to recieve the list.
01119  * listLength: number of 32 bit words in the list.
01120  * *slavePrimList: Address of start of source data for the list.
01121  *   - *slavePrimList = DEFAULT indicates that the slave primitive list is stored in
01122  *     the body of this SEND_SLAVE_LIST primtive starting just after the last
01123  *     SEND_SLAVE_LIST_IN structure element.
01124  * *slaveRepData: Address where master should put slave reply data if the
01125  *             START_SLAVE_LIST primitive is executed with getSlaveReply != 0.
01126  *   - *slaveRepData = DEFAULT indicates that the slave reply list should be stored
01127  *     in the body of a reply message to the START_SLAVE_LIST primtive.
01128  */
01129 #define SEND_SLAVE_LIST      (1 + (RW_FIFO))
01130 #define R_SEND_SLAVE_LIST    103
01131     struct SEND_SLAVE_LIST_IN {
01132         UINT32 slaveNumber;
01133         UINT32 listLength;
01134         UINT32 *slavePrimList;    /* DEFAULT value defined above */
01135         UINT32 *slaveRepData;     /* DEFAULT value defined above */
01136     };
01137 
01138 /*
01139  *  Start a slave DSP executing its primitive list by setting its inListRdy bit.
01140  * slaveNumber: ID of slave DSP to execute list
01141  * pauseMasterList != 0 if master DSP list execution pauses while slave executes list
01142  * getSlaveReply != 0 if the master should read the slave reply data
01143  */
01144 #define START_SLAVE_LIST      (1 + (SEND_SLAVE_LIST))
01145 #define R_START_SLAVE_LIST    103
01146 struct START_SLAVE_LIST_IN {
01147     UINT32 slaveNumber;
01148     UINT32 pauseMasterList;
01149     UINT32 getSlaveReply;
01150 };
01151 
01152 /* pause, resume or abort a slave list */
01153 #define SLAVE_LIST_OP      (1 + (START_SLAVE_LIST))
01154 #define R_SLAVE_LIST_OP    101
01155     struct SLAVE_LIST_OP_IN {
01156         UINT32 slaveNumber;
01157         UINT32 listOp;
01158     };
01159     #define LIST_PAUSE  0
01160     #define LIST_RESUME 1
01161     #define LIST_ABORT  2
01162 
01163 /* Build & send a command stream to the detector electronics. sendData will ship
01164    a command stream back to the VME host. */
01165 #define BUILD_STREAM          (1 + (SLAVE_LIST_OP))
01166 #define R_BUILD_STREAM        102
01167     struct BUILD_STREAM_IN {
01168         struct  CmdList cmdList;
01169         UINT32  cmdBuff, reset, chip, fibre;
01170         UINT32  dataLen;    //Length of the extra data, in bits.
01171         UINT32  *data;      //Start of the data for a command with large amounts of
01172                             //data (masks & some pixel commands).
01173     };
01174 
01175 #define SEND_STREAM          (1 + (BUILD_STREAM))
01176 #define R_SEND_STREAM        100
01177     struct SEND_STREAM_IN {
01178         UINT32 cmdBuff, captureSerOn;
01179     };
01180 
01181 /* configure a module, or send it's data (resident in memory) to control links.
01182    For input data, the pointer to configData is the start. */
01183 #define RW_MODULE_DATA     (1 + (SEND_STREAM))
01184 #define R_RW_MODULE_DATA   101
01185     struct RW_MODULE_DATA_IN {
01186         UINT32 readNotWrite, structId, moduleNum;
01187         ABCDModule *configData;
01188     };
01189     struct RW_MODULE_DATA_OUT {
01190         ABCDModule configData;
01191     };
01192     #define INIT_MODULE_CONFIG  0
01193     #define WORK_MODULE_CONFIG  1
01194     #define SPARE_MODULE_CONFIG  2
01195     #define N_MODULE_CONFIG_SETS ((SPARE_MODULE_CONFIG) -(INIT_MODULE_CONFIG) +1)
01196 
01197 
01198 #define SEND_CONFIG      (1 + (RW_MODULE_DATA))
01199 #define R_SEND_CONFIG    102
01200     struct SEND_CONFIG_IN {
01201         UINT32   cmdBuff,  captureSerOn, moduleNum[2], loop,
01202                  setLinks, restore, structId, groupId, dataType,
01203                  activeOnly, enableDataTaking;
01204     };
01205 
01206     #define NO_CONFIG_LOOP        0
01207     #define NORMAL_CONFIG_LOOP    1
01208     #define OFF_ROD_CONFIG_LOOP   2
01209 
01210     #define CONFIG_MODULE_BASIC  0
01211     #define CONFIG_MODULE_TRIM   1
01212     #define CONFIG_MODULE_ALL    2
01213 
01214     #define NO_MODULE 0xff
01215 
01216     #define MODULE_GROUP_0       0
01217     #define MODULE_GROUP_1       1
01218     #define MODULE_GROUP_2       2
01219     #define MODULE_GROUP_3       3
01220     #define MODULE_GROUP_4       4
01221     #define MODULE_GROUP_5       5
01222     #define MODULE_GROUP_6       6
01223     #define MODULE_GROUP_7       7
01224 
01225     #define MODULE_GROUP_ALL     8
01226     #define N_MODULE_GROUPS      (MODULE_GROUP_ALL)
01227 
01228 #define DSP_RESET      (1 + (SEND_CONFIG))
01229 #define R_DSP_RESET    100
01230     struct DSP_RESET_IN {
01231         UINT32  slvBits, forceSync, nAttempts, timeOut;
01232     };
01233 
01234 #define SET_ROD_MODE   (1 + (DSP_RESET))
01235 #define R_SET_ROD_MODE    100
01236     struct SET_ROD_MODE_IN {
01237         UINT32  mode, dataLen, *data;
01238     };
01239 
01240     /* Some modes are additive; e.g. CALIBRATION +LINK_DATA. The ROD will
01241        return an error for those modes which are incompatible. */
01242 
01243     /* NDT: Sets the data path according to the simulation type or link_data
01244             +capture,  sets the atlas running mode to true so that router is
01245             not allowed to apply back-pressure, and sets the link masks and
01246             assoc. variables according to the information stored in the 
01247             INIT module configuration set. */
01248     //Move all modes to rodConfig.h
01249     #define NORMAL_DATA_TAKING   1 
01250     //#define CALIBRATION          2 
01251     #define LINK_DATA            4
01252     #define CAPTURE_DATA         8
01253 
01254     #define SIMULATION_INMEM     16
01255     #define SIMULATION_DBGMEM    32
01256     #define SIMULATION_EVTMEM    64
01257 
01258 
01259 #define RW_MODULE_VARIABLE  (1 + (SET_ROD_MODE))
01260 /*  #define R_RW_MODULE_VARIABLE    100 */
01261 /*      struct RW_MODULE_VARIABLE_IN { */
01262 /*          UINT32  read,  sendToModule, structId, groupId, module, varType, dataLen; */
01263 /*          MDAT32 *data; */
01264 /*      }; */
01265 /*      struct RW_MODULE_VARIABLE_OUT { */
01266 /*          UINT32  dataLen; */
01267 /*          MDAT32 *data; */
01268 /*      }; */
01269 
01270 #define RW_BOC_DATA  (1 + (RW_MODULE_VARIABLE))
01271 #define R_RW_BOC_DATA    100
01272     struct RW_BOC_DATA_IN {
01273         UINT32  read, sendToBoc, dataLen, *data;
01274     };
01275     struct RW_BOC_DATA_OUT {
01276         BOCConfig bocCfgData;
01277     };
01278 
01279 
01280 #define LAST_MASTER_PRIMITIVE   (RW_BOC_DATA)
01281 #define NUM_MASTER_PRIMITIVES   ((LAST_MASTER_PRIMITIVE)-(MASTER_PRIMITIVES_BASE)+1)
01282 
01283 
01284 #if   defined(SCT_ROD)
01285     #define MASTER_SCT_PRIMITIVES_BASE 0x2800
01286 
01287 /*  //#define XXX (MASTER_SCT_PRIMITIVES_BASE)
01288     //#define LAST_MASTER_SCT_PRIMITIVE   (XXX)
01289     //#define NUM_MASTER_SCT_PRIMITIVES   \
01290     //  ((LAST_MASTER_SCT_PRIMITIVE)-(MASTER_SCT_PRIMITIVES_BASE)+1) */
01291 
01292     #define NUM_MASTER_SCT_PRIMITIVES  0
01293 
01294 #elif defined(PIXEL_ROD)
01295     #define MASTER_PIXEL_PRIMITIVES_BASE 0x2800
01296 
01297     #define TEST_GLOBAL_REG (MASTER_PIXEL_PRIMITIVES_BASE)
01298     #define R_TEST_GLOBAL_REG   112
01299         struct TEST_GLOBAL_REG_IN {
01300             UINT32 structId;
01301             UINT32 moduleId;
01302             UINT32 FEIndex; 
01303         };
01304         struct TEST_GLOBAL_REG_OUT {
01305             UINT32 testResult;
01306             UINT32 dataLen;
01307             MDAT32 *data;
01308         };
01309 
01310     #define LAST_MASTER_PIXEL_PRIMITIVE   (TEST_GLOBAL_REG)
01311     #define NUM_MASTER_PIXEL_PRIMITIVES   \
01312         ((LAST_MASTER_PIXEL_PRIMITIVE)-(MASTER_PIXEL_PRIMITIVES_BASE)+1)
01313 #endif
01314 
01315 
01316 #if   defined(SCT_ROD)
01317     #define NUM_PRIMITIVES ( (NUM_COMMON_PRIMITIVES)     \
01318                             +(NUM_SLAVE_PRIMITIVES)      \
01319                             +(NUM_MASTER_PRIMITIVES)     \
01320                             +(NUM_COMMON_SCT_PRIMITIVES) \
01321                             +(NUM_SLAVE_SCT_PRIMITIVES)  \
01322                             +(NUM_MASTER_SCT_PRIMITIVES)   )
01323 
01324 #elif defined(PIXEL_ROD)
01325     #define NUM_PRIMITIVES ( (NUM_COMMON_PRIMITIVES)       \
01326                             +(NUM_SLAVE_PRIMITIVES)        \
01327                             +(NUM_MASTER_PRIMITIVES)       \
01328                             +(NUM_COMMON_PIXEL_PRIMITIVES) \
01329                             +(NUM_SLAVE_PIXEL_PRIMITIVES)  \
01330                             +(NUM_MASTER_PIXEL_PRIMITIVES)   )
01331 
01332 #else
01333     #define NUM_PRIMITIVES ( (NUM_COMMON_PRIMITIVES) \
01334                             +(NUM_SLAVE_PRIMITIVES)  \
01335                             +(NUM_MASTER_PRIMITIVES)   )
01336 
01337 #endif
01338 
01339 /************************************************************************************
01340  *  Primitive function prototypes (not needed by the host processor).
01341  ************************************************************************************/
01342 #if (defined(I_AM_MASTER_DSP) || defined(I_AM_SLAVE_DSP))
01343 INT32 noPrimitive(struct PRIM_DATA *);
01344 
01345 INT32 echo(struct PRIM_DATA *);
01346 INT32 setErrMsgMask(struct PRIM_DATA *);
01347 INT32 pauseList(struct PRIM_DATA *);
01348 INT32 eventTrapSetup(struct PRIM_DATA *);
01349 INT32 setMemory(struct PRIM_DATA *);
01350 INT32 copyMemory(struct PRIM_DATA *);
01351 INT32 memoryTest(struct PRIM_DATA *);
01352 INT32 setLed(struct PRIM_DATA *);
01353 INT32 flashLed(struct PRIM_DATA *);
01354 INT32 sendData(struct PRIM_DATA *);
01355 INT32 moduleMask(struct PRIM_DATA *);
01356 INT32 setTrigger(struct PRIM_DATA *);
01357 INT32 startTask(struct PRIM_DATA *);
01358 INT32 taskOperation(struct PRIM_DATA *);
01359 INT32 test(struct PRIM_DATA *);
01360 INT32 writeBuffer(struct PRIM_DATA *);
01361 
01362 #if   defined(SCT_ROD)
01363 #elif defined(PIXEL_ROD)
01364 #endif
01365 
01366 INT32 startEventTrapping(struct PRIM_DATA *);
01367 INT32 stopEventTrapping(struct PRIM_DATA *);
01368 INT32 histogramSetup(struct PRIM_DATA *);
01369 
01370 #if   defined(SCT_ROD)
01371 #elif defined(PIXEL_ROD)
01372 #endif
01373 
01374 INT32 rwSlaveMemory(struct PRIM_DATA *);
01375 INT32 transSerialData (struct PRIM_DATA *);
01376 INT32 startSlaveExecuting(struct PRIM_DATA *);
01377 INT32 configSlave(struct PRIM_DATA *);
01378 INT32 rwRegField(struct PRIM_DATA *);
01379 INT32 pollRegField(struct PRIM_DATA *);
01380 INT32 rwFifo(struct PRIM_DATA *);
01381 INT32 sendSlaveList(struct PRIM_DATA *);
01382 INT32 startSlaveList(struct PRIM_DATA *);
01383 INT32 slaveListOp(struct PRIM_DATA *);
01384 INT32 buildStream(struct PRIM_DATA *);
01385 INT32 sendStream(struct PRIM_DATA *);
01386 INT32 rwModuleData(struct PRIM_DATA *);
01387 INT32 sendConfig(struct PRIM_DATA *);
01388 INT32 dspReset(struct PRIM_DATA *);
01389 INT32 setRodMode(struct PRIM_DATA *);
01390 INT32 rwModuleVariable(struct PRIM_DATA *);
01391 INT32 rwBocData(struct PRIM_DATA *);
01392 //INT32 configBoc(struct PRIM_DATA *);
01393 
01394 #if   defined(SCT_ROD)
01395 #elif defined(PIXEL_ROD)
01396     INT32 testGlobalReg(struct PRIM_DATA *);  
01397 #endif
01398 
01399 #endif  /* primitive parameters definition block */
01400 
01401 #endif

Generated on Mon Dec 8 18:03:58 2003 for SCT DAQ/DCS Software by doxygen1.3-rc3