Vx/IP-OptoDriver: VxWorks Driver for IP-OptoDriver

copyright (c) 1995 Compware Corp.

1. Overview 2. Features 3. Examples 4. Test Code

1. Overview

This note describes the usage of the 1.1 release of the vxWorks driver for the IP-OptoDriver. The driver supports up to 4 IP's, which may be installed upon a VME IP carrier (e.g., VIPC610/616/etc.), or on one of the 4 onboard IP slots of the Motorola MVME162 processor board.

The product offers 16 channels of optically coupled switching output- each channel may be switched ON or OFF after initialization. The vxWorks driver paradigm represents channels by devices, which are separately named and created. A 1 byte write operation to a channel device turns the channel on or off accordingly as the byte is 0 or non-zero. The semantics for the write - 0 meaning ON - match the hardware conventions. Although a device typically corresponds to a single channel, it is also possible to group several channels in one device. In this case, the same 1 byte write turns the whole group on or off. A read operation is also defined, always returning 1 byte. The value equals the last write to that device, or initial default. There are no ioctl commands for the IP Opto Driver, but the usual complement of configuration operations exist for driver initialization, IP registration, and device creation. There is also a Show routine to display information about all the IP's currently registered.

A test application is provided (ta2.c) which runs in conjunction with the Vx/IP-OptoInterruptor driver/equipment. It generates a suitably slow pattern of switching transitions on eight output lines which are monitored by the Interruptor. Both the Vx/IP-OptoDriver and Vx/IP-OptoInterruptor software/equipment are tested.

2. Features

2.1 Initialization

The driver itself is installed and initialized by

ipOptoDrv()

w ithout arguments. It fails only if the driver cannot be installed in vxworks, in that case r eturming "-1". Otherwise it r eturns "0". It also returns "0" if called after the driver is correctly installed, the call being then a no-op.

2.2 IP Registration

An IP-OptoDriver Industry pack is registered by

ipOptoDrvPackRegister(base, localBus, verbose)

which returns -1 if unsuccessful and otherwise a pack number (0-3) needed later for device creation.

"base" is the address of the IO space base address for this IP. This will either be the VME short i/o address (0- 0xFFFF) or the local MVME162 address, depending on the installation. If on the MVME162 board, a shorthand is available- set the base to a small number (0-3), which will be taken as the onboard slot number- 0 for A through 3 for D.

"localBus" is a BOOL, set TRUE (1) if the IP is onboard the local MVME162, FALSE (0) if on a VME carrier.

"verbose" is a BOOL, true if advisory and error messages are to be printed. If false, ipOptoDrvPackRegister will fail or succeed silently.

IpOptoDrvPackRegister fails if the IP is not found (bus error), has the wrong manufacturer, model number, or title ("IPAC") in the IP Prom ID space. The routine fails if the maximum number (presently 4) of IP's has already been installed. It also fails if the selftest (presently stubbed to succeed) on the IO space registers fails, if the memory allocation O/S operation fails, or if the specified address parameters are impossible (e.g, pointing to local RAM). If the IP has already been registered, the test succeeds as a no-op with an advisory message.

2.3 Device Creation

A device may be created for any grouping of the 16 output channels of the IP-OptoDriver. By convention, these lines are numbered as channels 1 through 16:

ipOptoDrvDevCreate ( name, pack, whichChans)

which r eturns "-1" if unsuccessful, "0" otherwise

"name" is a unique string such as "/ch1" to reference the device in open calls

"pack" is the pack number, as returned by ipOptoDrvPackRegister

"whichChans" is an array of integer channel numbers, representing the channels grouped under this device. Writes to this device apply to all channels in the group. The array of channels ends with a 0 element; there must be at least one channel in the group. Channels must be numbered between 1 and 16 inclusive.

IpOptoDrvDevCreate fails if the driver or pack are not installed, channel numbers are out of range, or if the memory allocation or device installation O/S operations fail. An advisory message is printed if channels grouped for this device overlap with those assigned to already created devices. In order to check for channel overlap, a queue of devices for each IP is maintained. The device being created is added to this queue. If the queue is found to be in an inconsistent state, an advisory message is printed. This message should not ever appear.

2.4 Read, Write, Open and Close

Write operations on open IP-OptoDriver devices:

write(fd, buffer, nbytes)

return "0" if they fail, or the byte count (always 1) if they succeed

"fd" is the file designator returned by open

"buffer" is the address to store read data

"nbytes" is available buffer size, Nbytes must be 1

The byte in the write buffer is 0 or 1 accordingly as the output is to be switched ON or OFF, respectively. It is desirable practice to use the constants IP_OPTODRV_LINES_ON and IP_OPTODRV_LINES_OFF, defined in ipOptoDrv.h, for the value to be placed in the write buffer.

Read operations on open IP-OptoDriver devices:

read(fd, buffer, nbytes)

"return" 0 if they fail, or the byte count (always 1) if they succeed

"fd" is the file designator returned by open

"buffer" is the address to store read data

"nbytes" is available buffer size, Nbytes must be 1

The byte read is 0 or 1 accordingly as the output is currently switched ON or OFF, respectively. This will match the last write to the same device, or the initial default (1).

Under some circumstances, an inconsistency can arise between the byte in the read buffer and the actual setting of the corresponding line. This can occur whenever there is overlap among device channel assignments. Read tracks the device itself, not the individual channels. Thus, accessing channels by means of other devices can change their status without changing the value that will be read from this device. To avoid this problem, do not use overlapping devices. In future versions of this driver, it may be desirable to supply an ioctl to return the actual line states for the several channels of a device.

Open and close operations are conventional, except that in release 1.1, at least, a mutual exclusion semaphore is taken at open time and given at close time. This means only 1 process may hold a device open at a time. The file designator, however, may be shared with care among processes. Another mutual exclusion semaphore guards access to pack wide resources, such as the IP register set.

If a process tries to open an IP-OptoDriver device, and it is already open, the process will hang until the previous file designator is closed. However, this close need not be done by the same process that opened it.

2.5 Show Routines

To display the status of installed Ip-OptoDrivers, use:

ipOptoDrvPackShow

without arguments. This displays, for each installed IP, the current bits of the output register, the ip base address, the state of the pack semaphore, and the total writes to the hardware outputs register. The queue of associated devices for each pack is tabulated, with current output states and write counts for each device.