#%TITLE% VMEDS.MAC
#
#%NAME%
#  Macros for accessing a VME bus through the vmeds device server.
#
#%OVERVIEW%
#  This macro set uses calls to the %B%vmeds%B% device server to emulate 
#  the %B%spec%B% functions for data access through VME controllers.%BR%
#  Only the memory area configured in the device server is accessible 
#  and all the functions require a first argument with the name of the 
#  device and the memory offset used by the device server to calculate 
#  absolute addresses.%BR%
#  The data types available are "D8" (the default), "D16" and "D32" and 
#  can be specified in the argument <dmode>.%BR%
#  The device server allows two types of data transfer a slower one (the 
#  default) that uses system functions to access the memory and can catch 
#  bus errors and a faster one that makes memory read/write operations 
#  directly.%BR%
#  The fast mode can be selected by using the string "fast" as last argument.
#  This mode should only be used when one is sure that the hardware is present
#  and the read/write operation is allowed, otherwise a device server crash may 
#  happen.%BR%
#  (NOTE: In the current version data blocks of more than one item cannot
#  be written in the VME memory using the fast mode)
#
#%EXAMPLE%
#  %DL%
#  %DT%vmeds_get("isg/vmeds109/1", 0x400)
#  %DD%Reads a single byte from offset 0x400.
#  %DT%vmeds_put("isg/vmeds109/1", 0x000, 0xffff, "D16")
#  %DD%Writes the word 0xffff at offset 0.
#  %DT%vmeds_move("isg/vmeds109/2", 0xff00, mdata, 256, "D32", "fast")
#  %DD%Reads the first 256 long words starting at offset 0xff00 into 
#      the array mdata using fast access mode.
#  %XDL%
#
#%END%



#%UU%(<device>, <offset> [, <dmode> [, "fast"]])
#%MDESC%
#  Reads a data item from the VME.
#
def vmeds_get(device, offset, dmode, cmode) '{
   local ldata
   ulong array ldata[1]

   vmeds_move(device, offset, ldata, 1, dmode, cmode)
   return(ldata[0])
}'


#%UU%(<device>, <offset>, <data> [, <dmode> [, "fast"]])
#%MDESC%
#  Writes the data item <data> in the VME.
#
def vmeds_put(device, offset, data, dmode, cmode) '{
   local ldata
   ulong array ldata[1]

   ldata[0] = data
   return vmeds_move(device, ldata, offset, 1, dmode, cmode)
}'

#%UU%(<device>, <from>, <to> [, <cnt> [, <dmode> [, "fast"]]])
#%MDESC%
#  Function that transfers data between the VME and %B%spec%B%.
#  The transfer direction is defined by the <from> and <to> arguments. 
#  One of them must be a non-associative array and the other a memory 
#  offset in the VME bus.
#  The number of data items copied is given by <cnt> or if it is missing 
#  by the number of elements in the array.
#  
#
def vmeds_move(device, from, to, cnt, dmode, cmode) '{
   local argin data offset type

   if (whatis("from") & 0x00010000) {
      data = "from"
      offset = to
   } else if (whatis("to") & 0x00010000) {
      offset = from
      data = "to"
   } else {
      print "Usage: vmeds_move(device, from, to [, cnt [, dmode [, fast]]])"
      exit
   }

   if (cnt <= 0 )
      cnt = array_op("cols", @data) * array_op("rows", @data)

   if (dmode == "D32") 
      type = 3
   else if (dmode == "D16")
      type = 2
   else
      type = 1


   if (data == "from") {
      ulong array argin[4 + cnt]
      argin[0] = type
      argin[1] = offset
      argin[2] = cnt
      argin[3:2+cnt] = from[0:cnt-1]
      argin[3+cnt] = -1
      if (cmode == "fast") {
         if (cnt > 1) {
            print "Writing data blocks in fast mode is not implemented."
            print "Using normal transfer mode."
            return esrf_io(device, "DevSetValue", argin)
         }
         return esrf_io(device, "DevWrite", argin)
      } else
         return esrf_io(device, "DevSetValue", argin)
   } else {
      ulong array argin[4]
      argin[0] = type
      argin[1] = offset
      argin[2] = cnt
      argin[3] = -1
      if (cmode == "fast")
         return esrf_io(device, "DevRead", argin, to)
      else 
         return esrf_io(device, "DevReadValue", argin, to)
   }
}'

#%UU%(<device>, <offset> [, <dmode>])
#%MDESC%
#  Version of %B%vmeds_get%B% that always uses fast transfer mode.
#
def vmeds_fget(device, offset, dmode) '{
   local ldata
   ulong array ldata[1]

   vmeds_move(device, offset, ldata, 1, dmode, cmode)
   return(ldata[0])
}'


#%UU%(<device>, <offset>, <data> [, <dmode>])
#%MDESC%
#  Version of %B%vmeds_put%B% that always uses fast transfer mode.
#
def vmeds_fput(device, offset, data, dmode) '{
   local ldata
   ulong array ldata[1]

   ldata[0] = data
   return vmeds_move(device, ldata, offset, 1, dmode, "fast")
}'

#%UU%(<device>, <from>, <to> [,<cnt> [, <dmode>]])
#%MDESC%
#  Version of %B%vmeds_move%B% that always uses fast transfer mode.
#
def vmeds_fmove(device, from, to, cnt, dmode) '{
   return(vmeds_move(device, from, to, cnt, dmode, "fast"))
}'
   
#%MACROS%
#%AUTHOR% P.Fajardo, (Original 8/98).
#  $Revision: 3.0 $ / $Date: 1999/03/17 10:12:51 $
#%TOC%