Vme v1 (Part 1)

int VmeOpenChannel (char* channel_name, char* access_type)
----------------------------------------------------------

opens a VME channel with name <channel_name> for VME accesses of 
type <access_type>. Valid access types are "pio", "dma" or "pio,dma"
for Programmed I/O (PIO) or DMA or both. 

Note: If you use DMA only e.g. access_type="dma" then you can ONLY
      use the VME access routines VmeDmaRead() and VmeDmaWrite().
      If DMA is not applicable it will be emulated with PIO.

Return value: 
   >=0 channel identifier in case of success.
    -1 in case of error. 
Errors: 
   Access type invalid or no channel space available. 

int VmeCloseChannel (int cid)
-----------------------------

Closes the VME channel with channel id <cid>.

Return value: 
   0 in case of success and -1 in case of error.
Errors: 
   Various.

void* VmeMapAddress (int cid, u_int vme_addr, int vme_size, int vme_am)
----------------------------------------------------------------------

maps VME address space at VME address <vme_addr> of size <vme_size> 
and with VME address modifier <vme_am>. The returned pointer can then 
be used to make VME programmed I/O.  
<cid> is the channel id returned by VmeOpenChannel().

NOTE: Not all VME CPUs support transparent VME access via pointer like
      the DEC Alpha boards. Therefore it is strongly recommanded to
      use the macros: Vme_D32READ, Vme_D32WRITE, 
                      Vme_D16READ, Vme_D16WRITE, 
                      Vme_D08READ, Vme_D08WRITE for Programmed I/O.

      Usage: Vme_D32READ(base, offset, value); <base> must be the
      address returned by VmeMapAddress(), <offset> is the offset from
      <base> in bytes and <value> is the value to be read or written.
      
Return value:
  - Pointer to mapped VME address space if channel is opened for PIO.
  - Dummy pointer 0xffffffff (-1) if channel is opened for DMA only.
  - NULL in case of an error.

Note: If you use a DMA only channel you must still call VmeMapAddress()
      to define the VME base address and the address type.

Errors:
  various.

void* VmeAllocateMemory (int cid, void* buf, int size, int type)
----------------------------------------------------------------

allocates or prepares memory for DMA to be used for this channel with id 
id <cid>. For DMA block transfers it is necessary to lock the memory 
space against being swapped out. DMA can be done faster if the buffer is 
locked in advance or if contiguous memory is used.  

Note: What is possible and how it is implemented is system dependent.
      On some systems this call is required to enable DMA. 

Parameters:

   buf : If buf = NULL new DMA buffer space of size <size> will be
         allocated otherwise the specified buffer with size <size>
         will be investigated and prepared for DMA. The type of the 
         DMA buffer can be defined with <type>. 
       
   size: Size of DMA buffer in bytes.

   type: Allows to specify the properties of either the buffer to be
         allocated or given by the user if case they are already known
         in advance. There are predefined variables which can be or'ed:

         Vme_MEMORY_UNKNOWN    : memory type is unknown.
         Vme_MEMORY_DEFAULT    : use default allocation type.
         Vme_MEMORY_FASTEST    : use fastest allocation type.

         Vme_MEMORY_CONTIGUOUS : contigous memory.
         Vme_MEMORY_LOCKED     : memory is already locked.
         Vme_MEMORY_MALLOC     : use malloc() to allocate memory.

Return value: 
   - Pointer of the buffer to be used for DMA. 
   - NULL in case of an error.

Errors: 
   various.

int VmeSetProperty (int cid, int prop, int value)
-------------------------------------------------

allows to define properties or options for the specified channel <cid>.
The properties which can be changed are defined as macros in Vme.h. 

Note: the availability of some options is system dependent. If they 
      are not supported they are ignored. Please be aware of that.

Return value: 
  0 in case of success and -1 in case of error. 
Errors: 
  various. an none existing option will not result in an error! 

int VmeGetProperty(int cid, int prop)
-------------------------------------

not yet implemented

int VmeSetExceptionHandling(int mode)
-------------------------------------

defines the way exceptions, mainly bus errors but also segmentation 
faults or others are handled. Most systems need a defined cleanup 
before the program exists. For this reason a set of exceptions 
(signal) are captured by default. This can be changed if necessary. 

Parameters:

 mode = Vme_EXCEPTION_NONE   : No exception handling. It is the users
                               responsibility to handle the signals and
                               to do the necessary cleanup.
        Vme_EXCEPTION_CHECK  : This allows to check for bus errors
                               with function VmeCheckException().  
        Vme_EXCEPTION_EXIT   : Exit after an exception. An appropriate
                               cleanup will be done before. 
        Vme_EXCEPTION_PRINT  : Only print a message when an exception
                               occures.
        Vme_EXCEPTION_DEFAULT: like Vme_EXCEPTION_EXIT.

int VmeSetExceptionHandler(VmeExceptionHandler handler)
-------------------------------------------------------

defines an additional user exception handler. The function
<handler> will be called after an excpetion has occured.

Note: not available if vme exception mode is set to
      Vme_SET_EXCEPTION_NONE.

Parameters:

handler   : function given by the user of type:
            void MyHandler(int signal_nr).

int VmeGetBusErrorType(void)
----------------------------

returns the type of a previously occured bus error.

Note: this function should only be called once after
      a bus error has been signaled !

Return values: 

 Vme_BUS_ERROR_TYPE_UNKNOWN : not supported on this system
 Vme_BUS_ERROR_TYPE_TIMEOUT : time out bus error
 Vme_BUS_ERROR_TYPE_SLAVE   : bus error from slave

int VmeCheckException(void)
---------------------------

allows to check if an exception (mainly bus error) has
occured during the previous programmed VME access.

Return value:
 exception or signal number (see /usr/include/signal.h). 

int VmeRead  (int cid, int vme_off, char *buf, int len)
-------------------------------------------------------

see VmeWrite() below.

int VmeWrite (int cid, int vme_off, char* buf, int len)
-------------------------------------------------------

performs VME read and write operations e.g. copies <len> bytes between 
memory buffer <buf> and VME space at offset <vme_off> (in bytes) from 
the VME base address specified in VmeMapAddress(). The type of VME 
transfer can be specified by calling VmeSetProperty() previously: 

Vme_SET_COPY_AM       : VME address modifier
Vme_SET_COPY_DTYPE    : Data type D8, D16 or D32
Vme_SET_COPY_FIFO     : do not increment VME address
Vme_SET_DMA_THRESHOLD : if <len> is greater than this value 
                        DMA will be done (if supported).

The address modifier defines if the transfer is done in VME block mode
(if available) or programmed I/O (PIO). The threshold is set by default
to a resonable value (PIO=DMA) and is system dependent.

In case an option is not supported on a system like DMA/BLT or 
FIFO access a relevant programmed I/O will be done.

<cid> is the channel id returned by VmeOpenChannel().

Return value: 
 Bytes transfered in case of success and 0 in case of error. 
 Note: Some systems support transfer termination by bus error.
       In this case the returned value is lower than <len>.
Errors: 
 various but most likely bus error

int VmeDmaRead (int cid, int vme_off, char* buf, int len)
---------------------------------------------------------

see VmeDmaWrite() below.

int VmeDmaWrite (int cid, int vme_off, char* buf, int len)
----------------------------------------------------------

like VmeWrite() but the transfer is always done in DMA/BLT 
(if available).

This function was mainly introduced to do DMA/BLT as fast as possible
by reducing the function overhead (threshold etc.). This has some
small impact for portability (some systems do not allow FIFO access
in DMA etc.).

#define Vme_D32READ(vme_base,vme_ptr,data)  data = *(int  *)(vme_ptr)
---------------------------------------------------------------------

see Vme_D08WRITE() below.

#define Vme_D16READ(vme_base,vme_ptr,data)  data = *(short*)(vme_ptr)
---------------------------------------------------------------------

see Vme_D08WRITE() below.

#define Vme_D08READ(vme_base,vme_ptr,data)  data = *(char *)(vme_ptr)
---------------------------------------------------------------------

see Vme_D08WRITE() below.

#define Vme_D32WRITE(vme_base,vme_ptr,data) *(int  *)(vme_ptr) = data
---------------------------------------------------------------------

see Vme_D08WRITE() below.

#define Vme_D16WRITE(vme_base,vme_ptr,data) *(short*)(vme_ptr) = data
---------------------------------------------------------------------

see Vme_D08WRITE() below.

#define Vme_D08WRITE(vme_base,vme_ptr,data) *(char *)(vme_ptr) = data 
----------------------------------------------------------------------

Macros to perform fast programmed i/o in VME D08, D16 and D32.
On most systems these macros are implemented as pointer
assignment but some, like Alpha/OSF1, need special functions.

Note: Please use only these macros instead of pointer assignment !

Parameters:
  vme_base: Mapped VME base address returned by VmeOpenChannel().
  vme_ptr : Pointer into mapped VME space to read from or write to. 
  data    : value for VME write or result of VME read.

Vme_am.h, VME address modifiers

/* lower 2 bits of AM codes
 */
#define Vme_BLT64	0
#define Vme_DATA	1
#define Vme_PGM		2
#define Vme_BLT		3


/* 32-bit ("extended") addressing, non-privileged mode
 */
#define Vme_AM_A32N			0x08
#define Vme_AM_EXT_USR_BLT64		(Vme_AM_A32N+Vme_BLT64)
#define Vme_AM_EXT_USR_DATA		(Vme_AM_A32N+Vme_DATA)
#define Vme_AM_EXT_USR_PGM		(Vme_AM_A32N+Vme_PGM)
#define Vme_AM_EXT_USR_BLT		(Vme_AM_A32N+Vme_BLT)

/* this group is for 32-bit ("extended") addressing, supervisor mode
 */
#define Vme_AM_A32S			0x0c
#define Vme_AM_EXT_SUP_BLT64		(Vme_AM_A32S+Vme_BLT64)
#define Vme_AM_EXT_SUP_DATA		(Vme_AM_A32S+Vme_DATA)
#define Vme_AM_EXT_SUP_PGM		(Vme_AM_A32S+Vme_PGM)
#define Vme_AM_EXT_SUP_BLT		(Vme_AM_A32S+Vme_BLT)

/* Xtended Addressing Mode 
 */
#define Vme_AM_XAM			0x20

/* 16-bit ("short") addressing, non-privileged mode 
 */
#define Vme_AM_A16N			0x28
#define Vme_AM_SHORT_USR		Vme_AM_A16N
#define Vme_AM_SHORT_USR_IO		(Vme_AM_A16N+Vme_DATA)

/* 16-bit ("short") addressing, supervisor mode
 */
#define Vme_AM_A16S			0x2c
#define Vme_AM_SHORT_SUP		Vme_AM_A16S
#define Vme_AM_SHORT_SUP_IO		(Vme_AM_A16S+Vme_DATA)

/* 24-bit ("standard") addressing, non-privileged mode 
 */
#define Vme_AM_A24N			0x38
#define Vme_AM_STD_USR_BLT64		(Vme_AM_A24N+Vme_BLT64)
#define Vme_AM_STD_USR_DATA		(Vme_AM_A24N+Vme_DATA)
#define Vme_AM_STD_USR_PGM		(Vme_AM_A24N+Vme_PGM)
#define Vme_AM_STD_USR_BLT		(Vme_AM_A24N+Vme_BLT)

/* 24-bit ("standard") addressing, supervisor mode
 */
#define Vme_AM_A24S			0x3c
#define Vme_AM_STD_SUP_BLT64		(Vme_AM_A24S+Vme_BLT64)
#define Vme_AM_STD_SUP_DATA		(Vme_AM_A24S+Vme_DATA)
#define Vme_AM_STD_SUP_PGM		(Vme_AM_A24S+Vme_PGM)
#define Vme_AM_STD_SUP_BLT		(Vme_AM_A24S+Vme_BLT)