drvIpac - Industry Pack Driver

• Introduction
• Installation
• IPAC Driver Usage
• ipacAddCarrier
• ipacReport
• ipacInitialise
• Calls for use by IPAC Module Drivers
• ipmBaseAddr
• ipmCheck
• ipmValidate
• ipmIrqCmd
• ipmIntConnect
• ipmReport
• IPAC Carrier Drivers
• GreenSpring VIPC310
• GreenSpring VIPC610
• GreenSpring VIPC616
• GreenSpring ATC40
• Motorola MVME162
• Interface to IPAC Carrier Drivers

• TEWS Tip810 CANbus IP module
• GreenSpring Octal Serial IP module (RS232, RS422, RS485)

1. Introduction

To provide a generic IPAC carrier board interface for each IPAC module driver, all control of or requests for information about the carrier board goes via the IPAC driver which in turn calls the IPAC Carrier driver written for the particular type of carrier board. This carrier driver should be simple to write, comprising three or four short subroutines and an interface structure. On VMEbus, carrier drivers are available for the GreenSpring VIPC310, 610 and 616 boards, and a driver for the Motorola MVME162 that also works on the MVME172. On ISAbus the GreenSpring ATC40 carrier is now supported by a driver from Jeff Hill.

At present the IPAC driver is limited (by the size of an internal array) to controlling a maximum of 21 carrier boards, but this limitation should be easy to dispense with completely without altering any of its interfaces. Although designed primarily to be used from within an EPICS system, the software has been written to allow it to be used independent of the presence of EPICS in other vxWorks-based applications.

Installation

1. Edit the config/RELEASE file and set the correct path for EPICS_BASE at your site.
2. Run gnumake in the top level directory.

Bus Issues

The endian problem only exists when accessing I/O registers and the IPAC ID PROM using byte addresses. If all accesses occur using 16-bit read/write cycles then the problem disappears. This is usually done by changing the structure that declares the structure of a module's registers to use short instead of char and removing the `padding' char members that separate the registers (this change has been made to the ipac_idProm_t structure which is declared in drvIpac.h). This done the other changes are generally minor, usually consisting of masking off the top 8 bits of every value read from the hardware.

Some busses such as ISAbus do not support interrupt vectors and require a different approach to connecting Interrupt Service Routines up to the relevent hardware interrupts, although the IndustryPack standard does require that any IP module that generates interrupts should provide a vector. On ISA bus carriers this vector can be read by the carrier driver to work out which module caused the interrupt. A module driver should not need to know about the particular bus type its carrier is on, thus ipac now provides the routine ipmIntConnect to allow it to pass such issues off to the carrier driver to handle. The interface to this is very similar to the standard vxWorks intConnect routine.

2. IPAC Driver Usage

#include "drvIpac.h"

If it is necessary to build a copy of the driver for use without EPICS, the drvIpac.c file should be compiled with the -DNO_EPICS switch to disable the EPICS-specific code.

ipacAddCarrier

int ipacAddCarrier(ipac_carrier_t *pcarrier, char *cardParams);

Parameters

ipac_carrier_t *pcarrier

Pointer to the carrier driver structure which is the only interface to the IPAC Carrier driver. The same structure is used for every instance of the same type of carrier board. The carriers already supported provide the following structures which can be used here:

char *cardParams

String containing board-specific initialisation parameters which is passed to the carrier driver. For carrier boards which rely on jumpers to set the board address (e.g. the GreenSpring carrier boards), the settings for each particular board will be reflected in the parameter settings given here when registering that carrier. For boards such as the MVME162 where the addresses can be changed by the driver, this string may be used to indicate how the board should be initialised. See the specific documentation for each carrier driver (section 4 below) for the parameter string syntax.

Description

The code checks that the carrier descriptor table looks sensible, calls the initialise routine with the given card parameters, 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.

It may be necessary to remove a carrier temporarily from a system in some circumstances without wanting to have to change the carrier number allocated to higher numbered carriers. To allow this, it is legal to call this routine with a NULL (zero) carrier table address, which switches in the null carrier table instead. When this facility is used any module driver which attempts to access a slot on this carrier will be given error status returns by the module interface routines.

Returns

int

Examples

ipacAddCarrier(&vipc610_01, "0x6000,256");
ipacAddCarrier(NULL, "");
ipacAddCarrier(&vipc310, "0x6800");

ipacReport

int ipacReport(int interest);

Parameters

int interest

Interest level, defines how much information to provide in the report.

Description

Returns

int

ipacInitialise

int ipacInitialise(int after);

Parameters

int after

Not currently used, provided for compatibility with EPICS driver initialisation routine.

Description

Returns

int

3. Calls for use by IPAC Module Drivers

ipmBaseAddr

void *ipmBaseAddr(ushort_t carrier, ushort_t slot, ipac_addr_t space);

Parameters

ushort_t carrier

Carrier number; identifies a particular carrier board in the system. The carriers are given numbers sequentially starting from zero according to the order in which they were registered by calling ipacAddCarrier.

ushort_t slot

Slot number; identifies the particular IP slot on the carrier board, starting from zero. The number of slots available varies with the type of the carrier board - the VIPC310 and MVME172 provide 2, the VIPC610, VIPC616, ATC40 and MVME162 each have four slots.

ipac_addr_t space

Value identifying the IP address space to be queried. This parameter is an enumerated type, and must be one of the following values which are defined in the header file:

Description

All IP modules must provide an ID prom to indicate the module type (space = ipac_addrID). Most modules need register I/O locations, which are in the I/O space (space = ipac_addrIO). Some types of module also provide memory (space = ipac_addrMem), but if this is not required the carrier may allow it to be disabled, in which case the carrier driver will return a NULL for this address space. Some carriers also provide a 32-bit wide I/O space for accessing 32-bit registers on Dual-slot IP modules (space = ipac_addrIO32); carriers which do not support this will return NULL for this space.

Returns

void *

Pointer to the beginning of the IP address space for the given carrier/slot, or NULL pointer.

ipmCheck

int ipmCheck(ushort_t carrier, ushort_t slot);

Parameters

ushort_t carrier, ushort_t slot

Module identification - see above

Description

Returns

int

ipmValidate

int ipmValidate(ushort_t carrier, ushort_t slot,
                uchar_t manufacturerId, uchar_t modelId);

Parameters

ushort_t carrier, ushort_t slot

Module identification - see above

uchar_t manufacturerId

IPAC Manufacturer Identification Number, as allocated by GreenSpring. This number should be given in the Programmer's Documentation for the IPAC module.

uchar_t modelId

IPAC Model Identification Number, as allocated by the module manufacturer. This number should be given in the Programmer's Documentation for the IPAC module.

Description

The manufacturer and model identification numbers allow a Module Driver to ensure that the correct hardware has been installed in the particular slot which the driver has been told to control. If a driver supports more than one type of module, it should check each module type individually by calling ipmValidate with each manufacturer/model pair it can control until it finds a match.

Returns

int

ipmIrqCmd

int ipmIrqCmd(ushort_t carrier, ushort_t slot,
              ushort_t irqNumber, ipac_irqCmd_t cmd);

Parameters

ushort_t carrier, ushort_t slot

Module identification - see above

ushort_t irqNumber

The IPAC specification provides two interrupt lines for each module. This parameter identifies the interrupt to the Carrier Driver. It should have the value 0 or 1 only.

ipac_irqCmd_t cmd

This parameter gives the action required, and is an enumerated type defined in the header file. Because some carrier boards do not provide software access to their interrupt controllers, there is only one command which must be supported by all carriers. Module Drivers can be written to utilise the additional functions if they are available.

Description

The Interrupt Priority (often also known as interrupt level) commands are defined to be numerically the same as the level number they select. Level 0 effectively disables the interrupt. Level 7 is not recommended within vxWorks as it is non-maskable and can cause the kernel to panic. The irqGetLevel command returns the level currently set. Carrier boards which have fixed interrupt levels will not support setting the interrupt level but the driver may still able to return the level number.

The irqEnable command must be supported by all Carrier Drivers, and must be called by all Module Drivers if they wish to use interrupts. The Carrier Driver routine is responsible for calling the vxWorks sysIntEnable routine if this is required to allow IPAC interrupts to be seen by the CPU. The corresponding irqDisable command is not necessarily supported by all carriers however -- the module driver must disable interrupts using the control registers on the IP module itself if this is necessary. A Carrier Driver must not implement the irqDisable command as a call to the vxWorks sysIntDisable routine because this would stop any other devices which still need this interrupt level from working.

Returns

int

Other values may also be returned depending on the Driver and command used.

ipmIntConnect

int ipmIntConnect (ushort_t carrier, ushort_t slot, ushort_t vecNum, 
                   void (*routine)(int parameter), int parameter);

Parameters

ushort_t carrier, ushort_t slot

Module identification - see above

ushort_t vecNum

Interrupt vector number

void (*routine)(int parameter)

Modules Interrupt Service Routine to be connected

int parameter

Context parameter passed to Interrupt Service Routine

Description

VxWorks' interrupt vectoring mechanism varies between bus types, and ipmIntConnect allows a module driver to connect its routine to an interrupt vector from a particular IPAC module without knowing the requirements of the particular bus type. Some carrier drivers will need to maintain a private interrupt dispatch table if the bus type (i.e. ISA) does not support interrupt vectoring.

Returns

int

Other values may also be returned depending on the Driver and vector used.

ipmReport

char *ipmReport(ushort_t carrier, ushort_t slot);

Parameters

ushort_t carrier, ushort_t slot

Module identification - see above

Description

Returns

char *

Pointer to a static, printable string.

Sample Output

"C0 S1 : 0xB1/0x01 - M0 L4,5"

4. IPAC Carrier Drivers

GreenSpring VIPC310

The IPAC Carrier Driver for this board is found in the file drvVipc310.c which exports only the symbol vipc310 for use as the carrier descriptor table with ipacAddCarrier.

Configuration Parameter String Format

The Memory Base Address of the VIPC310 card is set using the same jumpers as the I/O base address and is always 256 times the I/O base address, but in the VME A24 address space. The factory default for the memory base address is thus 0x600000.

If the memory size parameter is omitted or set to zero then neither IP module provides any memory space. Legal memory size values are 0, 64, 128, 256, 512, 1024 or 2048. The memory size interacts with the memory base address such that it is possible to set the existence of memory in either slot independently by suitable adjustment of the base address.

Configuration Examples

ipacAddCarrier(&vipc310, "0x6000")

This indicates that the carrier has its I/O base set to 0x6000, and neither slot uses any memory space.

ipacAddCarrier(&vipc310, "1000,512")

Here the I/O base is set to 0x1000, and there is 512 Kbytes of memory on each module, with the IP module A memory at 0x100000 and module B at 0x180000.

ipacAddCarrier(&vipc310, "0xfe00, 128")

The I/O Base is at 0xfe00, and hence the carrier board Memory Base address is 0xfe0000. However because the memory size is set to give each module 128 Kbytes of memory space, module A cannot be selected (128 K = 0x020000, so the module Memory Base would be decoded at 0xfc0000 but can't be accessed there because this is below the Memory Base address for the board).

Interrupt Commands Supported

GreenSpring VIPC610

The IPAC Carrier Drivers for the two board versions are found in the files drvVipc610.c and drvVipc610_01.c which export the symbols vipc610 and vipc610_01 respectively for use as the carrier descriptor tables with ipacAddCarrier.

Note that as from version 1.1 of this software vipc610_01 is a new name for the original vipc610 symbol which has been changed to allow support for the standard board. Use of the wrong symbol may result in interrupts from modules in slots B through D being ignored.

Configuration Parameter String Format

The Memory Base Address of the VIPC610 card is set using the same jumpers as the I/O Base Address and is always 256 times the I/O Base Address, but in the VME A24 address space. The factory default for the Memory Base address is thus 0x600000.

If the memory size parameter is omitted or set to zero then none of the IP modules on the carrier provide any memory space. Legal memory size values are 0, 64?, 128, 256, 512, 1024 or 2048. The memory size interacts with the Memory Base Address setting such that it is possible to exclude memory from the lower slots while still providing access to memory in the later slots by suitable adjustment of the base address.

Configuration Examples

ipacAddCarrier(&vipc610, "0x6000")

This indicates that the VIPC610 carrier board has its I/O base set to 0x6000, and none of the slots provide memory space.

ipacAddCarrier(&vipc610_01, "1000,128")

Here the I/O base is set to 0x1000, and there is 128Kbytes of memory on each module, with the IP module A memory at 0x100000, module B at 0x120000, module C at 0x140000 and D at 0x160000. The board is actually a VIPC610-01.

ipacAddCarrier(&vipc610, "7000,1024")

The I/O base is at 0x7000, and hence the carrier memory base is 0x700000. However because the memory size is set to 1024 Kbytes, modules A, B and C cannot be selected (1024 K = 0x100000, so they are decoded at 0x400000, 0x500000 and 0x600000 but can't be accessed because these are below the base address for the board).

Interrupt Commands Supported

GreenSpring VIPC616

Configuration Parameter String Format

The meaning of the second number depends upon whether the third (decimal) integer is present in the string or not. If there is no third number then the second number gives the Memory Base Address of the card in the VME A32 space. In this case each module is allocated a fixed 8 Mbytes of memory space by the carrier.

If all three numbers are given then the second number is the Memory Base Address of the card in VME A24 address space, and the third number gives the size of the memory space in Kbytes allocated to each IP module. This is the VIPC610 compatibility mode, and the Memory Base Address and Memory Size parameters are used and interact in exactly the same way as with the VIPC610.

Configuration Examples

ipacAddCarrier(&vipc616, "0x6000")

This indicates that the board has its I/O base set to 0x6000, and none of the slots provide memory space.

[I'm not sure that this example is correct; ommitting the MBA may result in an error. I don't have a VIPC616 to check this out with, so the driver is untested.]

ipacAddCarrier(&vipc616, "1000,8000000")

Here the I/O base is set to 0x1000, and each module is allocated 8Mb of VME A32 memory space starting at 0x80000000. This puts IP module A memory at 0x80000000, module B at 0x80800000, module C at 0x81000000 and D at 0x81800000.

ipacAddCarrier(&vipc616, "7000,700000,1024")

The I/O base is at 0x7000 and the carrier memory base is at 0x700000 in the VME A24 address space. However because the memory size is set to 1024 Kbytes, modules A, B and C cannot be selected (1024 K = 0x100000, so they are decoded at 0x400000, 0x500000 and 0x600000 but can't be accessed because these are below the base address).

Interrupt Commands Supported

GreenSpring ATC40

Motorola MVME162 and MVME172

When this CPU board is used the IPAC carrier driver drvIpMv162.c can control the IP slots on the board. The ipacAddCarrier carrier descriptor table parameter is ipmv162 for this driver. The carrier initialisation routine has the following additional return-code meanings (see also ipacInitialise above):
 

Configuration Parameter String Format

A, B, C and D

These select the IP slot (also identified as slots 0 through 3) which is to be controlled by the following commands, up to the appearance of the next of these slot selection characters.

l=level1[,level2]

Sets the interrupt level for the slot interrupters to the decimal values given by level1 and level2 respectively. If the second IP interrupt is not used by the particular module the ,level2 part may be omitted and this interrupt will be disabled. The default setting is for both interrupts to be disabled.

m=base,size

Enables the slot memory space and sets the base address for the slot to the hexadecimal value given by base, with extent given by the size parameter in kilobytes. NB size cannot be omitted.

r=recovery

This programs the slot recovery timer on the IPIC chip to be at least recovery microseconds (legal values are between 0 and 8 inclusive). This option should only be required with some early IP module designs.

w=width

The IPIC chip can alter the way in which the IP module memory space is addressed and is controlled using this option. By default or with a w=16 setting the memory will be initialised to be 16 bits wide with direct mapping of CPU addresses to IP memory addresses. By using the setting w=8 it is possible to access only the odd bytes of the IP memory space, i.e. only the 8 least significant bits of the data bus are used (other carrier boards may not support this type of operation so this facility should be used with care). The w=32 setting permits the memory space on double-width IP modules to be accessed using 32-bit transfers; this should be used on the even-numbered slot of the pair only.

Configuration Example

ipacAddCarrier &ipmv162, "A:m=0x80000000,1024 l=5,3 w=8 r=2 B:l=2"

Slot 0 is set up for a slow (recovery time 2µs) memory board with 1 Mbyte of 8-bit wide RAM, addressed at 0x80000000 and with interrupt priorities set for levels 5 and 3.

Slot 1 has no memory space, and just a single interrupt at priority level 2.

Interrupt Commands Supported

5. Interface to IPAC Carrier Drivers

#include "drvIpac.h"

The sole interface between the Carrier Driver and the IPAC driver is through the ipac_carrier_t typedef structure given in the header file. Note that this has changed slightly since version 2.0 with the addition of the carrier parameter to the initialise routine, and the new intConnect routine. This is defined as follows:

typedef struct {
    char *carrierType;                 /* String describing carrier board type */
    ushort_t numberSlots;              /* Number of IPAC devices this carrier can hold */
    int (*initialise)(char *cardParams, void **cPrivate, ushort_t carrier);
                                       /* Initialise carrier and return *cPrivate */
    char *(*report)(void *cPrivate, ushort_t slot);
                                       /* Return string giving status of this slot */
    void *(*baseAddr)(void *cPrivate, ushort_t slot, ipac_addr_t space);
                                       /* Return base addresses for this slot */
    int (*irqCmd)(void *cPrivate, ushort_t slot, ushort_t irqNumber,
                  ipac_irqCmd_t cmd);  /* Interrupt control */
    int (*intConnect)(void *cPrivate, ushort_t slot, ushort_t vecNum,
                      void (*routine)(int parameter), int parameter);
                                       /* Connect routine to interrupt vector */
} ipac_carrier_t;

The remaining structure members are function pointers to the routines which control the carrier board. The cPrivate parameter passed to these functions points to a structure which must be defined and allocated by the carrier driver and can be used to hold information about a particular carrier board (for example the board base address). The IPAC driver stores the cPrivate pointer which is returned by the initialise routine, and passes the same pointer back to the other routines when referring to that particular carrier board at a later stage.

The intConnect function pointer may be set to NULL if the standard vxWorks intConnect provides all the funtionality needed to install an interrupt vector - this is probably only needed for ISA bus carriers.

The other parameters to the routines are identical to those described in detail in the corresponding IPAC Driver routines above. The IPAC Driver performs parameter checking on the slot and irqNumber parameters before calling the Carrier Driver routine, so these values can be used with confidence.

The simplest way to write a carrier driver is to copy the VIPC310 or MVME162 driver and modify one of these for the new board type. The MVME162 driver interfaces to the IPIC chip and can be used as a basis for carrier drivers which provide extensive control over the IPAC slots. The VIPC310 board is totally dumb, and thus provides the simplest possible example of a carrier driver.