svtvme API Draft

General rules.

1. Global names: all global variable and function names must start with the SVTVME string, Upper/lower case does not matter but uniqueness to the package is required for VxWorks. See: http://www-b0.fnal.gov:8000/computing/vxworks/symbol_table.html
2. parameter passing. Use the same syntax for read and write, so for functions that access single words, the variable with the value is always passed as pointers, not by value. I.e. funct(..., int * value) bot if you write value or if you read value.
3. special values. There is no special menaing associated to "strange" values of parameters. If a request is made to read 0 words, nothing happens. Specific functinos are defined for reading entire memories or fifos.
4. return values: the funcions always returns an information. Negative values are reserved for errors. 0 and positive means success. Logical functions (svtvme_isXXX) return 1 if true, 0 if false.
5. Encapsulation: the user code will access everything via functions, will never deal with any internal strucutre. The only variables that the user code has to know are the svtvme_t strucutre that the user creates for each physical boars, the list of object Id's for each board type, and the Id's of each baord type (same as board ID in the prom).

Global variables/functions:

• int svtvme_setGlobalFlag(char *flag, int *value);
  sets the given global interal flag to the indicated value
• int svtvme_getGlobalFlag(char *flag, int *value);
  read the value for the indicated flag

Board handle creation/tuning:

• svtvme_t *svtvme_openBoard (char *cpu, int slot, int board_type);
  Opens for access one SVT board. At this time all internal svtvme strucutres are initialised if/as needed. Arguments are:
  • char *cpu: internet name of the crate cpu
  • int slot : slot number in the crate
  • int board_type: the board_type from the list of possibility defined in svtvme_public.h. They are all defined SVT boards plus a generic SVTB board that allow basic operation on an "unknown" slot, like reading the IDPROM.
  The board handle has internal state variables that store the board type (SVTB/HF/MRG/HB/AMS/AMB/TF/XTFA/XTFC/SC) and the flags for different ways to operate the board: protect (if set vme acces request are executed only if legal: i.e. if Freeze and/or TMode are required they are checked first). locked (if set no write operation is allowed) debug (if set verbose messages are printed, a couple of levels may be good, or a couple different flags). for these: >0=set, 0=non-set
• int svtvme_setBoardFlag(svtvme_t *board, char *flag, int *value);
  sets the given interal flag to the indicated value
• int svtvme_setBoardDebugFile(svtvme_t *board, FILE *file);
  sets the given interal flag to the indicated value
• int svtvme_getBoardFlag(svtvme_t *board, char *flag, int *value);
  read the value for the indicated flag
• void svtvme_closeBoard (svtvme_t *board);
  Board handle deletion

Single board access:

• int svtvme_getBoardId(svtvme_t *board, int *id);
  returns the board type ID (HF/MRG/HB/AMS/AMB/TF/XTFA/XTFC/SC) from the ID prom. This allows to open tentatively a slot with whatever ID, find out what is really there, then destroy the handle and create a new one with the proper board ID.
• int svtvme_getBoardSN(svtvme_t *board, int *sn);
  returns board serial number from ID prom. To read more prom data, use the generic readMemory (see below)
• int svtvme_init(svtvme_t * board);
  performs svt_init
• int svtvme_setState(svtvme_t *board, int object, int *state);
  sets the indicated object belonging to board into the desired state. object is an enumerated data type that spans all possible meaningfull bit sets of the boards various registers. state is a numeric value. The state is passed right aligned even for bit fields embedded in the mid of long registers, needed shift is taken care of internally, as well as the case where a read/modify/write of a long register is needed.
• int svtvme_getState(svtvme_t *board, int object, int *state);
  reads the current value, any meeded mask and/or shift is applied so to return right aligned values.
• int svtvme_checkState(svtvme_t *board, int object, int *state);
  test is the given object is in the given state and returns 1/0.
• int svtvme_isFrozen(svtvme_t *board);
  tests if Spy buffers for a given board are in frozen state. Note that this is all that it takes before reading the spy's since we do not implement separate freeze for the buffers. If instead the user wants to check the hardware of the boards reading the status of the freeze bit of all registers, the svtvem_testState should be used.
• int svtvme_isFull(svtvme_t *board, int channel);
  
• int svtvme_isEmpty(svtvme_t *board, int channel);
  
• int svtvme_isHeld(svtvme_t *board, int channel);
  

  for the following data-sendig functions I would like a general scheme to acknowledge/disregard the Hold, note by the way that this may not be possible from all boards, or may involve performance penalty, e.g. for HB/AMS where one has to go to single word write+read instead of block transfer. I suggest a tentative scheme and/but wellcome suggestions. Note that for HB/AMS if hold check is required and there indeed hold, the program will get stuck forever waiting for hold to clear, while other boards (merger e.g.) will deal with it in hardware so is up to user to make sure data transfer is finished before checking results. **************NB XTF-A is a special case************** the channel argument is there just for XTF-A (1-12) otherwise is ignored. XTF-A will also need some special functions to better deal with its wide L1 input fifo and SPy and output Spy buffer, and for complex sendings involving more then one output channel at the same time.

• int svtvme_obeyHold(svtvme_t *board);
  
• int svtvme_sendDataOnce(svtvme_t *board, int channel, int nw, uint4 *data);
  
• int svtvme_sendingDone(svtvme_t *board, int channel);
  1 if the given baord has finished sending whichever data was previously requested to send. An alternative name could be svtvme_clearToSend
• int svtvme_sendDataLoop(svtvme_t *board, int channel, int nw, uint4 *data);
  
• int svtvme_stopData(svtvme_t *board, int channel);
  in general a stop-sending-data is usefull also for non-loop, since the sender board my have been halted by a Hold flag and the user just wants to reset it to idle
• int svtvme_startDataLoop(svtvme_t *board, int channel);
  for example in the merger board is possible to restart the loop from the beginning without re-downloading the data.
• int svtvme_readMemoryFragment(svtvme_t *board, int memory, uint4 offset, int nw, uint4 *data);
  I depserately need a better name for this one. It reads the given number of words at a specified offset.
• int svtvme_writeMemoryFragment(svtvme_t *board, int memory, uint4 offset, int nw, uint4 *data);
  
• int svtvme_readMemory(svtvme_t *board, int memory, uint4 *data);
  this reads the full memory, it figures out the size from the memory name. data must be properly diemnsioned by caller.
• int svtvme_writeMemory(svtvme_t *board, int memory, uint4 *data);
  
• int svtvme_checkMemory(svtvme_t *board, int memory, uint4 *data);
  check the board memory content againt the data array passed in argument and returns 0/1
• int svtme_testMemory(svtvme_t *board, int memory, int ntimes);
  test the correct working of the indicated RAM, by repeating ntimes the following: - fill with random numbers - read back and check - fill with the complementary of the previous values - read back and check if ntimes<0 the test is halted at the first error, otherwise the number of errors is reported. if ntimes=0 it returns doing nothing Here the idea is eventually to do this on the crate cpu for maximum speed, so the loop can not be handled by the caller. Some more arguments/flags should be devised so that one can optionally save memory by computing the pseudo-random sequence as data are written/read, at cost of some performance (single word acces vs. block). Maybe better a flag for the different behaviors, rather then negative arg..
• int svtvme_testRegister(svtvme_t *board, int register, int verbose);
  test the correct working of the indicated R/W register doing the following: - write all 0 and read back - write all 1 and read back - rotate 0 - rotate 1 returns 1 if success, 0 if error. If verbose=1 then prints out details of errors if any.
• int svtvme_checksum(svtvme_t *board, int memory);
  computes the 32-bit checksum of the given RAM
• int svtvme_readFifo(svtvme_t *board, int channel, int nw, uint4 *data);
  read from a FIFO nw words no check done.
• int svtvme_readAllFifo(svtvme_t *board, int channel, int maxWords, uint4 *data, int *readWords);
  reads the given FIFO until is empty, up to maxWords are read and returned.
• int svtvme_readSpy(svtvme_t *board, int spy, int nw, uint4* data, int *readWords);
  reads the last nw words from the indicated spy buffer, if the pointer is

  ---

  Stefano Belforte
  Last modified: Mon Aug 7 20:40:07 CDT 2000