The Gemini Multi-Conjugate Adaptive Optics System project has decided to adopt Xycom as its manufacturer of choice to supply an IPAC carrier board and various IPAC modules. The motivation for using IPAC is to be able to provide cost effective functionality in one VME slot. There are a range of IPAC modules that provide functionality such as digital I/O and analog I/O. Since the carrier board is capable of hosting 4 modules and occupies one VME slot, we can tailor this slot to provide the desired mixture of digital and analog I/O.
The Xycom IPAC carrier board and its various modules did not have software support already available from the EPICS community. As part of the MCAO project, we have developed this support and the details of its use are documented here. In particular, we have developed EPICS support for the carrier board and 3 modules. These modules are:
The Xycom-9660 is a non-intelligent, 6U high, VME board. It provides an interface to the VME backplane for up to 4 IPAC modules. Data access is through the front panel. All data and register access to the IP modules are available as offsets from the base address of the carrier board. The front panel contains 4 LED's that indicate successful access to each of the on-board IPAC modules, this is very helpful in debugging problems. The carrier board supports two interrupt requests per IPAC module. It effectively maps these interrupts to one of the seven available interrupt request lines on the VME backplane.
There is one bank of jumpers on this board that allows the base address of the board to be configured. The carrier board is shipped with a default factory setting of 0x0000. The carrier board interfaces with the VMEbus as a 1K byte block of address locations in the VMEbus short I/O address space.
The way in which a driver for an IPAC carrier board is implemented within EPICS follows a very well defined methodology. Essentially, there is a generic IPAC driver already available for EPICS and each new carrier board needs to provide certain functions to interface to this generic driver. The generic driver is called "drvIpac" and was developed by Andrew Johnson (see his description at drvIpac). We have followed this approach in implementing the EPICS support for this carrier board. Essentially, four interface functions have been written:
This function is called from "ipacAddCarrier" which itself is called from within the vxWorks/EPICS startup script. The purpose of this function is to probe the VME memory space to make sure that communication with the board is possible and to initialise the board by setting the appropriate registers as required.
This function returns the base address, given a slot number on the carrier board and an address space. Note that many IPAC modules use two address spaces, this is because the IPAC module itself can have memory onboard. Typically the I/O base address of the module is in A16 space whilst any onboard memory is mapped into A24 space. We do not have to worry about this with the modules we have chosen for MCAO because none of them contain any onboard memory.
This function sets up interrupt control handling. Typically, it will enable the VME interrupt address level being used. We use level 6 for handling interrupts. This is the highest priority non-maskable interrupt level permitted by the VME specification.
This function returns information about the status of the module in each slot of the carrier board. It is called from "ipacReport", which is usually called from the vxWorks shell.
For the user of the Xycom-9660 carrier board software, the details of the four functions above are immaterial. The most important public function that the user will need to understand is "ipacAddCarrier" which is part of the generic IPAC driver.
int ipacAddCarrier(ipac_carrier_t *pcarrier, char *cardParams);This routine should be called from the vxWorks/EPICS start-up script. It registers a particular carrier board with the generic IPAC driver. It must be called once for each carrier board in the system. The order is which carriers are registered with this routine defines the carrier number they will be allocated, starting from zero for the first board registered.
The first argument to the routine is a pointer to the carrier descriptor table. In the case of the Xycom-9660 board, this will always be &xy9660.
For the Xycom-9660 board, the second argument will be the base address of the carrier board, e.g. "0x0400". This base address must agree with that selected via the hardware jumpers on the carrier board itself.
When called, the function checks that the carrier descriptor table looks sensible, calls the "initialise" routine (as described above), then saves the carrier private pointer and carrier table address in an internal array. The card number allows the same descriptor table to be used for all carriers of the same type i.e. all Xycom-9660 carrier boards use the same descriptor table.
Note that the driver can be used without EPICS by compiling the code with the flag "-D NO_EPICS".
The Xycom-2440 Digital Input Module allows for the monitoring of 32 optically-isolated inputs. It is a high-speed board for which zero wait states are required. Access times for all data transfer cycles are described in terms of "wait" states. Zero wait states implies that all cycles complete in 250ns. There are three different models of this particular board allowing a selection of input ranges from +/-4 to +/-60 volts. The board we have chosen for MCAO operates in the +/-4 to +/-18 volt range.
The board is capable of generating an interrupt for a change in each input channel. Whether the interrupt is generated for a low-to-high or a high-to-low transition is software programmable through an event register. Since this register occupies 1 byte and there are 32 inputs, the resolution for controlling the interrupts is 4 channels (nibble) per bit of the event register. Note that we can detect both types of transition for a single input channel but to do this requires bi-wiring of the channels with a wire jumper at the termination panel.
For each set of 8 input channels (defined as a port), we can configure the debounce time through software. The debounce time is the amount of time that must elapse before a transition to a new state is confirmed to have taken place.
There are no jumper settings for this module.
Two software modules have been written for this card, "drvXy2440.c" and "devXy2440.c". These correspond to the vxWorks/EPICS device driver and EPICS device support respectively. The device driver can be compiled for use with vxWorks only by compiling with the "-D NO_EPICS" directive.
This module can be configured through software to run in two different modes: standard mode and enhanced mode. The difference between the modes is that interrupts are only generated in enhanced mode and debounce is only configurable in enhanced mode.
The vxWorks interface is provided by a set of four functions. We describe their use below.
int xy2440Report( int interest );
int xy2440Initialise( void );
int xy2440Create( char *name, ushort_t card, ushort_t slot,
char *modeName, char *intHandlerName, char *usrFunc, short vector,
short event, short debounce );
usrFunc( char *name, int port, int bit )
long xy2440Read( char *name, short port, short bit, int readFlag,
unsigned short *pval, int debug );
The unique name which identifies this particular module in the system.
The number of the port we want to read from. Ports are numbered from 0 to 3.
The number of the bit, within the port, we wish to read. Bits are numbered from 0 to 7.
Lines similar to the following must be placed in the vxWorks startup script:
Note that a separate call to xy2440Create is necessary for each Xycom-2440 module in the system. Only one call to xy2440Initialise is necessary as this initializes all the modules.
The EPICS interface is defined by the device support that has been written to support this module. Within the EPICS software architecture, the device support layer links EPICS records to the device driver layer. Device support has been written for the BI, MBBI and MBBIDIRECT EPICS records. Within an EPICS input record, the communication link to the hardware is configured through two fields, the DTYP field and the INP link. For the Xycom-2440 module, these fields should be specified as follows:
Here, name, is the unique name of this module within the system. This should always be the same as that specified as the first parameter in the call to xy2440Create.
<p> is the port number we wish to read from.
<b> is the bit number we wish to read from.
For the MBBI and MBBIDIRECT records, it is essential to configure the NOBT field. This is the number of bits you wish to read. An MBBI record is capable of reading up to and including 4 bits, an MBBIDIRECT record is capable of reading up to and including 16 bits. The read will begin at the position indicated by the P and B parameters in the INP link specification.
It is worth pointing out two important differences between the EPICS support for the Xycom-2440 module and EPICS support for the Xycom-240 digital I/O board which is distributed as part of EPICS base:
A single line, for each Xycom-2440 module, similar to the following should be placed in the startup script:
The explicit call to xy2440Initialise, as shown in the vxWorks startup script, is unnecessary as this will be called automatically when EPICS initializes via the execution of iocCore.
The Xycom-2445 module allows control of up to 32 optically isolated outputs. This is achieved via 32 bipolar SSR's. It is a high-speed board for which zero wait states are required. Access times for all data transfer cycles are described in terms of "wait" states. Zero wait states implies that all cycles complete in 250ns. This module is loop-back compatible with the Xycom-2440 module. The output channels are split into 4 ports of 8 channels. Each group of 8 channels can be connected to common for low side switching. In this configuration, the module is TTL compatible. For safety reasons, when the module is powered-up or a system reset occurs, the SSR's will be disabled and the outputs are turned off.
There are no jumper settings for this module.
Two software modules have been written for this card, "drvXy2445.c" and "devXy2445.c". These correspond to the vxWorks/EPICS device driver and EPICS device support respectively. The device driver can be compiled for use with vxWorks only by compiling with the "-D NO_EPICS" directive.
The vxWorks interface is provided by a set of five functions. We describe their use below.
int xy2445Report( int interest );
int xy2445Initialise( void );
int xy2445Create( char *name, ushort_t card, ushort_t slot );
long xy2445Read( char *name, short port, short bit, int readFlag,
unsigned short *pval, int debug );
The unique name which identifies this particular module in the system.
The number of the port we want to read from. Ports are numbered from 0 to 3.
The number of the bit, within the port, we wish to read. Bits are numbered from 0 to 7.
long xy2445Write( char *name, short port, short bit, int writeFlag,
long value, int debug );
The unique name which identifies this particular module in the system.
The number of the port we want to write to. Ports are numbered from 0 to 3.
The number of the bit, within the port, we wish to write to. Bits are numbered from 0 to 7.
A line similar to the following must be placed in the vxWorks startup script:
Note that a separate call to xy2445Create is necessary for each Xycom-2445 module in the system.
The EPICS interface is defined by the device support that has been written to support this module. Within the EPICS software architecture, the device support layer links EPICS records to the device driver layer. Device support has been written for the BO, MBBO and MBBODIRECT EPICS records. Within an EPICS output record, the communication link to the hardware is configured through two fields, the DTYP field and the OUT link. For the Xycom-2445 module, these fields should be specified as follows:
Here, name, is the unique name of this module within the system. This should always be the same as that specified as the first parameter in the call to xy2445Create.
<p> is the port number we wish to write to.
<b> is the bit number we wish to write to.
For the MBBO and MBBODIRECT records, it is essential to configure the NOBT field. This is the number of bits you wish to write. An MBBO record is capable of writing up to and including 4 bits, an MBBODIRECT record is capable of writing up to and including 16 bits. The write will begin at the position indicated by the P and B parameters in the OUT link specification.
The EPICS startup script entry is identical to the vxWorks startup script entry above.
The Xycom-5320 module allows monitoring of up to 20 differential or 40 single-ended channels. Each analog value is converted to a 12-bit digital value using a successive approximation ADC with an 8.5\265s conversion time. The board is capable of a maximum system throughput of 100,000 samples per second using the pipe-lined mode of operation. In this mode, the board is configured to read the next channel while the current channel is being converted.
Input acquisition can be triggered via software or by an external hardware input for synchronization to external events. One nice feature of the board is that it contains four voltage sources and an analog ground reference to enable automatic calibration. The gain of each channel is separately configurable through software. Valid values for the gain are 1, 2, 4 or 8.
This module contains two banks of jumpers. One bank enables the input voltage range to be selected, the other bank enables an external or internal power supply to be used. One of three input voltage ranges can be chosen: -5 to +5 V, -10 to +10 V or 0 to +10 V. For the power, if the internal supply is chosen, then the +/- 12 V back-plane source is used via the P1 connector. If the external supply is chosen the user must supply a +/- 15 V power source via the P2 connector. Note that the input voltage ranges: -10 to +10 V and 0 to +10 V can only be achieved by using an external power source, otherwise the digitized values will be clipped.
Two software modules have been written for this card, "drvXy5320.c" and "devXy5320.c". These correspond to the vxWorks/EPICS device driver and EPICS device support respectively. The device driver can be compiled for use with vxWorks only by compiling with the "-D NO_EPICS" directive.
The vxWorks interface is provided by a set of five functions. We describe their use below.
int xy5320Report( int interest );
So, for each channel configured at boot time, the following information is given:
int xy5320Initialise( void );
int xy5320Create( char *name, ushort_t card, ushort_t slot,
char *voltRangeName, char *modeName, int numSamples,
char *filename );
long xy5320ReadChannel( char *name, int channel,
unsigned long ftvl, void *prval );
The unique name which identifies this particular module in the system.
long xy5320ReadArray( char *name, int startIndex, int numChan,
unsigned long ftvl, void *prval );
The unique name which identifies this particular module in the system.
Two lines similar to the following must be placed in the vxWorks startup script:
Note that a separate call to xy5320Create is necessary for each Xycom-5320 module in the system. Only one call to xy5320Initialise is necessary as this initializes all the modules.
The EPICS interface is defined by the device support that has been written to support this module. Within the EPICS software architecture, the device support layer links EPICS records to the device driver layer. Device support has been written for the AI and the Waveform EPICS records. Within an EPICS input record, the communication link to the hardware is configured through two fields, the DTYP field and the INP link. For the Xycom-5320 module, these fields should be specified as follows:
Here, name, is the unique name of this module within the system. This should always be the same as that specified as the first parameter in the call to xy5320Create.In the next two paragraphs, filename, refers to the file named in the call to xy5320Create. For the AI record, <c> is the channel number we wish to read from. This must have previously been configured through filename. For the Waveform record, <c> is no longer the channel number. It is the index of the channel in filename at which we want the array to begin.
The FTVL field within the Waveform record allows the user to specify the type of data within the array. This device support uses the setting of this field to decide whether to return the corrected digitized values (FTVL=LONG) or the analog values (FTVL=DOUBLE). The Waveform record contains a field, NELM that usually specifies the number of channels to be read. It is slightly different for this device support. NELM must be set to twice the number of channels you wish to read plus 1. That is:
The reason is as follows. We want to return not only the analog values of the channels but the channel numbers themselves and the number of elements read. The format of the returned array is as follows:
The reason for returning all of these values in a single array is to circumvent the problem of atomic Channel Access "gets". If these data were split between 2 or 3 different record fields, then it would always be possible to obtain a dataset that is inconsistent. By using an array, we do not have this problem.
Note that the output from the Waveform record can be connected to an input of a genSub record and the values of the array can be manipulated with ease.
A single line, for each Xycom-5320 module, similar to the following should be placed in the startup script:
The explicit call to xy5320Initialise, as shown in the vxWorks startup script, is unnecessary as this will be called automatically when EPICS initializes via the execution of iocCore.
The software is available for download from the link given in the table below:
Version EPICS Release Filename 1.0 R3.13.x xycomIpac-1.0.tar.gz
When expanded, the gzipped tar file contains a simple three level directory structure. The top-level directory will be called xycomIpac, under which will be found src. Under src there are 4 directories: xy2440, xy2445, xy5320 and xy9660. The driver, device support and DBD files for each module can be found in the appropriate directory. To build these into your application: