drvIpac/drvIpac.html

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="Author" content="Andrew Johnson">
   <meta name="Description" content="How to use the drvIpac Industry Pack Carrier driver software">
   <meta name="KeyWords" content="EPICS, IndustryPack">
   <title>drvIpac &ndash; Industry Pack Driver</title>
</head>
<body bgcolor="#FFFFFF">

<center>
<h1>
drvIpac &ndash; Industry Pack Driver</h1>

Version 2.14

<address>
Andrew Johnson</address></center>

<ol>
<li>
<a href="#section1">Introduction</a>

<ul>
<li>
<a href="#Installation">Installation</a></li>
</ul></li>

<li>
<a href="#section2">IPAC Driver Usage</a>

<ul>
<li>
<a href="#ipacAddCarrier">ipacAddCarrier</a></li>

<li>
<a href="#ipacAddNullCarrier">ipacAddNullCarrier</a></li>

<li>
<a href="#ipacLatestCarrier">ipacLatestCarrier</a></li>

<li>
<a href="#ipacReport">ipacReport</a></li>

<li>
<a href="#ipacInitialise">ipacInitialise</a></li>
</ul></li>

<li>
<a href="#section3">Routines for use by IPAC Drivers</a>

<ul>
<li>
<a href="#ipmBaseAddr">ipmBaseAddr</a></li>

<li>
<a href="#ipmCheck">ipmCheck</a></li>

<li>
<a href="#ipmValidate">ipmValidate</a></li>

<li>
<a href="#ipmIrqCmd">ipmIrqCmd</a></li>

<li>
<a href="#ipmIntConnect">ipmIntConnect</a></li>

<li>
<a href="#ipmReport">ipmReport</a></li>

<li>
<a href="#ipcCheckId">ipcCheckId</a></li>

</ul></li>

<li>
<a href="#section4">IPAC Carrier Drivers</a>

<ul>
<li>
<a href="#VIPC310">GE Fanuc Embedded VIPC310</a></li>

<li>
<a href="#VIPC610">GE Fanuc Embedded VIPC610</a></li>

<li>
<a href="#VIPC616">GE Fanuc Embedded VIPC616</a></li>

<li>
<a href="#TVME200">Tews TVME-200</a></li>

<li>
<a href="#ATC40">SBS ATC40</a></li>

<li>
<a href="#MVME162">Motorola MVME162/172</a></li>

<li>
<a href="#AVME9660">Acromag AVME-9660/9668/9670</a></li>

<li>
<a href="#Hy8002">Hytec 8002/8004</a></li>
</ul></li>

<li>
<a href="#section5">Interface to IPAC Carrier Drivers</a></li>
</ul>

<p>
See also the following Module Drivers which are included with drvIpac:</p>

<ul>

<li>
<a href="drvTip810.html">TEWS Tip810 CANbus IP module</a></li>

<li>
<a href="tyGSOctal.html">GE Fanuc Embedded Octal Serial IP module (RS232, RS422,
RS485)</a></li>

<li>
<a href="IP520.html">Acromag IP520 module (8 EIA/TIA-232E serial ports)</a></li>

</ul>

<hr>


<h2>
<a NAME="section1"></a>1. Introduction</h2>

<p>
This document describes the software interface to a generic Industry Pack
(IPAC) driver module for EPICS, which was originaly written as part of a
<a href="drvTip810.html">CANbus EPICS device driver</a> for the
<a href="http://www.gemini.edu/">Gemini</a> and UKIRT telescopes. The
original purpose of the generic IPAC driver was to ensure that the CANbus
driver would not be restricted to use with a single carrier board but could be
used with different carriers as required, including with more than one type of
carrier board simultaneously. The use of the generic driver also ensures that
additional IPAC modules and drivers for other interfaces can be added without
affecting the functioning of the CANbus driver.</p>

<p>
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.
Carrier drivers are available for most of the common IP carrier boards.</p>

<p>
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 without altering the drvIpac API should any user ever need more
than 21 carriers in a single IOC.</p>

<h3>
<a NAME="Installation"></a>Installation</h3>

<p>
The drvIpac subsystem is an EPICS &lt;supporttop&gt; application which
can also be used to build IPAC module drivers. To install and use the the ipac
support, download the tar file from the
<a href="http://www.aps.anl.gov/epics/download/modules/">APS Support Module
Downloads</a> page. These instructions assume you already have EPICS R3.14.x
installed and built (this software should work with any release of EPICS Base
from 3.14.9 onwards). Four steps are then required to install and build the
software:</p>

<ol>

<li>
Edit the configure/RELEASE file and set the correct path for EPICS_BASE at
your site.</li>

<li>
If you don't need all of the module drivers included with the distribution,
edit the top level Makefile and comment out the lines mentioning driver
directories you don't need.</li>

<li>
Edit the drvIpac/drvIpac.dbd file and uncomment the set of IPAC Carrier drivers
that you will be using at your site. This step can also be performed later by
copying the drvIpac.dbd file to an IOC application and modifying it there
instead.</li>

<li>
Run <tt>gnumake</tt> in the top level directory.</li>

</ol>

<h3>
<a NAME="Bus Issues"></a>OS and Bus Issues</h3>

<p>
This version if the IPAC driver supports little-endian as well as big-endian
CPUs, and provides a means of isolating module drivers from some of the
differences between interrrupt handling and module probing on different
busses.</p>

<p>
The endian problem only exists when accessing I/O registers and the IPAC ID PROM
using byte addresses. In drvIpac all accesses are made using 16-bit read/write
cycles, so there are no known issues with endianness.  This is done by declaring
the structure of a module's registers using <tt>epicsUInt16</tt> variables
instead of <tt>char</tt>. With this done the only other requirement is to mask
off the top 8 bits of every value read from the hardware.</p>

<p>
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
<a href="#ipmIntConnect">ipmIntConnect()</a> 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.</p>

<p>
Some IPAC driver routines such as ipmCheck() need to be able to tell whether
they can safely access the ID Prom space for a given IP slot. If the carrier
driver provides a moduleProbe() routine this will be consulted; if not, the
devReadProbe() routine from devLib is used. It is assumed that probing one
location in the ID Prom is sufficient to answer the question for all ID Prom
locations.</p>

<hr>


<h2>
<a NAME="section2"></a>2. IPAC Driver Usage</h2>

<p>
The driver provides a C header file <i>drvIpac.h</i> for use by both module
and carrier drivers.</p>

<pre>#include "drvIpac.h"</pre>

<p>
This header file declares the necessary structures, enumerated types and
functions provided by the driver. These are individually documented below.</p>

<p>This software can no longer be built for use without EPICS.</p>

<hr>


<h3>
<a NAME="ipacAddCarrier"></a>ipacAddCarrier</h3>

<p>
Used to register a carrier board and the appropriate carrier driver software
for it with the IPAC Driver.  Up to release 2.5 this call was used directly
inside IOC startup scripts, but from release 2.6 onwards the carrier drivers
provided with drvIpac all contain their own routines for use in startup
scripts, which allows initialization from the EPICS ioc shell as well as from
the VxWorks shell.  See the documentation for the specific carrier board in
<a href="#section4">section 4</a> below for the name of the new initialization
routine.</p>

<pre>int ipacAddCarrier(ipac_carrier_t *pcarrier, const char *cardParams);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<tt>ipac_carrier_t *pcarrier</tt></dt>

<dd>
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.</dd>

<dt>
<tt>const char *cardParams</tt></dt>

<dd>
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 SBS 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
(<a href="#section4">section 4</a> below) for the parameter string syntax.</dd>

</dl>

<h4>
Description</h4>

<p>
This routine will usually be called from the EPICS start-up script.
Some types of carrier may need additional initialisation before or after
registering, but this method using the card parameter string should be
sufficient for most carriers. Note that only the carrier <tt>initialise()</tt>
routine is called at this stage. The order in which carriers are registered
with this routine defines the carrier number which they will be allocated,
starting from zero for the first board registered.</p>

<p>
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.</p>

<p>
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.</p>

<p>
As long as the carrier table is not full, <tt>ipacAddCarrier()</tt> will always
increment its internal carrier number on every call, thus a carrier driver
failure will not cause all subsequent carriers to silently change their carrier
numbers. In the event of an error, the null carrier table is used for the
current carrier number instead of the requested table, which will cause module
driver initialization to fail for that carrier.</p>

<p>
This routine is not provided as an IOC Shell command; individual carrier
drivers must register their own <tt>ipacAdd...()</tt> commands to use
instead.</p>

<h4>
Returns</h4>

<dl>
<dt>
<tt>int</tt></dt>

<dd>
<table BORDER=2>
<tr>
<th>Symbol/Value</th>

<th>Meaning</th>
</tr>

<tr>
<td>0</td>

<td>OK</td>
</tr>

<tr>
<td>S_IPAC_tooMany</td>

<td>Carrier Info Table full</td>
</tr>

<tr>
<td>S_IPAC_badTable</td>

<td>Carrier Table invalid</td>
</tr>

<tr>
<td>(others values)</td>

<td>from carrier initialisation routine.</td>
</tr>
</table></dd>
</dl>

<h4>
Examples</h4>

<blockquote>
<pre>ipacAddCarrier(&amp;vipc610_01, "0x6000,256");
ipacAddCarrier(0, "");
ipacAddCarrier(&amp;vipc310, "0x6800");</pre>
</blockquote>


<hr>
<h3>
<a NAME="ipacAddNullCarrier"></a>ipacAddNullCarrier</h3>

<p>
Reserves a carrier number for a board that is not currently being
used.</p>

<pre>int ipacAddNullCarrier();</pre>

<h4>
Description</h4>

<p>
This routine provides a way to reserve a carrier number for a carrier
board that is not currently in use.</p>

<h4>
Returns</h4>

<dl>
<dt>
<tt>int</tt></dt>

<dd>
<table BORDER=2>
<tr>
<th>Symbol/Value</th>

<th>Meaning</th>
</tr>

<tr>
<td>0</td>

<td>OK</td>
</tr>

<tr>
<td>S_IPAC_tooMany</td>

<td>Carrier Info Table full</td>
</tr>
</table></dd>
</dl>

<h4>
Example</h4>

<blockquote>
<pre>ipacAddNullCarrier();
</blockquote>


<hr>
<h3>
<a NAME="ipacLatestCarrier"></a>ipacLatestCarrier</h3>

<p>
Gets the carrier number of the most recently added carrier board.</p>

<pre>int ipacLatestCarrier(void);</pre>

<h4>
Description</h4>

<p>
Returns the index into the carrier table of the most recently added carrier
board, or USHRT_MAX if the most recent call to ipacAddCarrier could not be
fulfilled because the carrier table was already full. The value returned can
always be used as the carrier argument to any drvIpac routine without checking
it first; if the carrier board was not properly initialized for any reason then
these routines will return a failure status of some kind.</p>

<p>
This routine is not provided as an IOC Shell command, it would not be
useful.</p>

<h4>
Returns</h4>

<dl>
<dt>
<tt>int</tt></dt>

<dd>
<table BORDER=2>
<tr>
<th>Symbol/Value</th>

<th>Meaning</th>
</tr>

<tr>
<td>0 thru 20</td>

<td>Carrier number of latest board added</td>
</tr>

<tr>
<td>USHRT_MAX</td>

<td>Carrier table was full</td>
</tr>
</table></dd>
</dl>


<hr>
<h3>
<a NAME="ipacReport"></a>ipacReport</h3>

<p>
Prints a report on stdout giving the status of all known IPAC carriers.</p>

<pre>int ipacReport(int interest);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<tt>int interest</tt></dt>

<dd>
Interest level, defines how much information to provide in the report.</dd>
</dl>

<h4>
Description</h4>

<p>
Prints information on each known carrier board and slot according to the
specified interest level. Level&nbsp;0 lists all the carriers defined, with the
number of IPAC slots each one supports. Level&nbsp;1 gives details on each slot
on the carriers: the Manufacturer and Model ID bytes of the installed module if
one is present, and the Carrier Driver's report for that slot (see <a
href="#ipmReport">ipmReport</a> below). Level&nbsp;2 adds the CPU address of
each memory space for the slot.</p>

<h4>
Returns</h4>

<dl>
<dt>
<tt>int</tt></dt>

<dd>
<table BORDER=2>
<tr>
<th>Symbol/Value</th>

<th>Meaning</th>
</tr>

<tr>
<td>0</td>

<td>OK.</td>
</tr>
</table></dd>
</dl>


<hr>
<h3>
<a NAME="ipacInitialise"></a>ipacInitialise</h3>

<p>
Initialise the IPAC driver.</p>

<pre>int ipacInitialise(int after);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<tt>int after</tt></dt>

<dd>
Not currently used, provided for compatibility with EPICS driver initialisation
routine.</dd>
</dl>

<h4>
Description</h4>

Null routine, does nothing.

<h4>
Returns</h4>

<dl>
<dt>
<tt>int</tt></dt>

<dd>
<table BORDER=2>
<tr>
<th>Symbol/Value</th>

<th>Meaning</th>
</tr>

<tr>
<td>0</td>

<td>OK.</td>
</tr>
</table></dd>
</dl>

<hr>


<h2>
<a NAME="section3"></a>3. Routines for use by IPAC Drivers</h2>

<p>
The routines documented below are provided for use by the module and carrier
drivers which use the services of the generic IPAC driver (routine names
beginning with <q>ipm</q> are intended for module drivers, routine names
beginning with <q>ipc</q> are intended for carrier drivers). In most cases these
routines will only need to be called at initialisation time, the exception being
some run-time use of the <tt>ipmIrqCmd()</tt> routine. A module driver should be
informed by other means which carrier and slot the particular IPAC module it is
to control has been installed in, although it is possible to search each carrier
slot in turn for a particular module using the Manufacturer and Model ID
codes.</p>

<h3>
<a NAME="ipmBaseAddr"></a>ipmBaseAddr</h3>

<p>
Returns Base CPU address of selected IP address space</p>

<pre>void *ipmBaseAddr(int carrier, int slot, ipac_addr_t space);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<a NAME="carrierSlot"></a><tt>int carrier</tt></dt>

<dd>
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 with <tt>ipacAddCarrier</tt>.</dd>

<dt>
<tt>int slot</tt></dt>

<dd>
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 &ndash; for example the VIPC310 and MVME172 provide two, the TVME200 and
Xy9660 each have four slots.</dd>
</dl>

<p>
Together these two parameters uniquely identify a specific IPAC module in the
system, and these are used in this way by all of the following routines.</p>

<dl>
<dt>
<tt>ipac_addr_t space</tt></dt>

<dd>
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:

<blockquote>
<table BORDER=2>
<tr>
<th>IP Address Space</th>

<th><tt>space</tt></th>
</tr>

<tr>
<td>ID Prom Space</td>

<td><tt>ipac_addrID</tt></td>
</tr>

<tr>
<td>Register Space</td>

<td><tt>ipac_addrIO</tt></td>
</tr>

<tr>
<td>32-bit Register Space</td>

<td><tt>ipac_addrIO32</tt></td>
</tr>

<tr>
<td>Memory Space</td>

<td><tt>ipac_addrMem</tt></td>
</tr>
</table>
</blockquote>
</dd>
</dl>

<h4>
Description</h4>

<p>
Checks its input parameters, then calls the carrier driver. This will return a
pointer to the location of the address space indicated by the <tt>space</tt>
parameter.</p>

<p>
All IP modules must provide an ID prom to indicate the module type (<tt>space =
ipac_addrID</tt>). Most modules need register I/O locations, which are in the
I/O space (<tt>space = ipac_addrIO</tt>). Some types of module also provide
memory (<tt>space = ipac_addrMem</tt>), 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 (<tt>space =
ipac_addrIO32</tt>); carriers which do not support this will return NULL for
this space.</p>

<h4>
Returns</h4>

<dl>
<dt>
<tt>void *</tt></dt>

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

<hr>


<h3>
<a NAME="ipmCheck"></a>ipmCheck</h3>

<p>
Check on the presence of an IPAC module at the given carrier and slot
number.</p>

<pre>int ipmCheck(int carrier, int slot);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<tt>int carrier, int slot</tt></dt>

<dd>
Module identification &ndash; see <a href="#carrierSlot">above</a></dd>
</dl>

<h4>
Description</h4>

<p>
Checks to make sure the carrier and slot numbers are legal, then probes for the
presence of an ID Prom, delegating this operation to the carrier driver if it
provides a moduleProbe() routine. If access to a the ID Prom space is safe it
delegates checking the IPAC header to <tt>ipcCheckId()</tt>.</p>

<h4>
Returns</h4>

<dl>
<dt>
<tt>int</tt></dt>

<dd>
<table BORDER=2>
<tr>
<th>Symbol/Value</th>

<th>Meaning</th>
</tr>

<tr>
<td>0</td>

<td>OK</td>
</tr>

<tr>
<td>S_IPAC_badAddress</td>

<td>Bad carrier or slot number</td>
</tr>

<tr>
<td>S_IPAC_badDriver</td>

<td>Carrier driver returned NULL ID address</td>
</tr>

<tr>
<td>S_IPAC_noModule</td>

<td>No IP module installed</td>
</tr>

<tr>
<td>S_IPAC_noIpacId</td>

<td>IP Module identifier not found</td>
</tr>
</table></dd>
</dl>

<hr>


<h3>
<a NAME="ipmValidate"></a>ipmValidate</h3>

<p>
Validates a particular IPAC module type at the given carrier &amp; slot
number.</p>

<pre>int ipmValidate(int carrier, int slot,
                int manufacturerId, int modelId);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<tt>int carrier, int slot</tt></dt>

<dd>
Module identification &ndash; see <a href="#carrierSlot">above</a></dd>

<dt>
<tt>int manufacturerId</tt></dt>

<dd>
IPAC Manufacturer Identification Number, as allocated by SBS. This number
should be given in the Programmer's Documentation for the IPAC module.</dd>

<dt>
<tt>int modelId</tt></dt>

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

<h4>
Description</h4>

<p>
Uses <tt>ipmCheck</tt> to ensure the carrier and slot numbers are legal,
probe the IDprom and check that the IDprom looks like an IPAC module. Then
calculates and verifies the CRC for the ID Prom, and compares the manufacturer
and model ID values in the Prom to the ones given.</p>

<p>
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
<tt>ipmValidate</tt> with each manufacturer/model pair it can control until it
finds a match.</p>

<p>
Releases of drvIpac before 2-9 did not recognize Format-2 ID PROMS as defined in
the VITA spec. From release 2-9 on this software should be compatible with
modules having either Format-1 or Format-2 ID PROMS. In the newer format the
PROM is specified to be 16 bits wide rather than 8, and various fields including
the Manufacturer and Model numbers have been made wider. The calculated CRC is
also wider, but some IP Module manufacturers are setting the CRC field to all
zeros rather than calculating the correct CRC value for it. As a result, the
<tt>ipmValidate</tt> routine will not check the CRC of a Format-2 ID Prom if its
CRC field is zero.</p>

<h4>
Returns</h4>

<dl>
<dt>
<tt>int</tt></dt>

<dd>
<table BORDER=2>
<tr>
<th>Symbol/Value</th>

<th>Meaning</th>
</tr>

<tr>
<td>0</td>

<td>OK</td>
</tr>

<tr>
<td>S_IPAC_badCRC</td>

<td>CRC Check failed</td>
</tr>

<tr>
<td>S_IPAC_badModule</td>

<td>Manufacturer or model IDs wrong</td>
</tr>

<tr>
<td>S_IPAC_badAddress</td>

<td>Bad carrier or slot number</td>
</tr>

<tr>
<td>S_IPAC_badDriver</td>

<td>Carrier driver returned NULL ID address</td>
</tr>

<tr>
<td>S_IPAC_noModule</td>

<td>No IP module installed</td>
</tr>

<tr>
<td>S_IPAC_noIpacId</td>

<td>IP Module identifier not found</td>
</tr>
</table></dd>
</dl>

<hr>


<h3>
<a NAME="ipmIrqCmd"></a>ipmIrqCmd</h3>

<p>
Manipulate the carrier board interrupt controller.</p>

<pre>int ipmIrqCmd(int carrier, int slot,
              int irqNumber, ipac_irqCmd_t cmd);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<tt>int carrier, int slot</tt></dt>

<dd>
Module identification &ndash; see <a href="#carrierSlot">above</a></dd>

<dt>
<tt>int irqNumber</tt></dt>

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

<dt>
<tt>ipac_irqCmd_t cmd</tt></dt>

<dd>
This parameter gives the action required (see table in Description below), and
is an enumerated type defined in the header file. Because some carrier boards
do not provide software access to their interrupt controllers most of the
commands are optional. Module Drivers may be written to utilise the additional
functions if they are available.</dd>
</dl>

<h4>
Description</h4>

<p>
Checks input parameters, then passes the interrupt command request to the
equivalent Carrier Driver routine. The driver is only required to support the
command <tt>ipac_irqEnable</tt>; for other commands it may return the status
code <tt>S_IPAC_notImplemented</tt> and do nothing. Commands available are as
follows:</p>

<blockquote>
<table BORDER=2>
<tr>
<th>Command Description</th>

<th>cmd</th>
</tr>

<tr>
<td>Selects Interrupt Priority 0 (disabled)</td>

<td><tt>ipac_irqLevel0</tt></td>
</tr>

<tr>
<td>Selects Interrupt Priority 1</td>

<td><tt>ipac_irqLevel1</tt></td>
</tr>

<tr>
<td>Selects Interrupt Priority 2</td>

<td><tt>ipac_irqLevel2</tt></td>
</tr>

<tr>
<td>Selects Interrupt Priority 3</td>

<td><tt>ipac_irqLevel3</tt></td>
</tr>

<tr>
<td>Selects Interrupt Priority 4</td>

<td><tt>ipac_irqLevel4</tt></td>
</tr>

<tr>
<td>Selects Interrupt Priority 5</td>

<td><tt>ipac_irqLevel5</tt></td>
</tr>

<tr>
<td>Selects Interrupt Priority 6</td>

<td><tt>ipac_irqLevel6</tt></td>
</tr>

<tr>
<td>Selects Interrupt Priority 7</td>

<td><tt>ipac_irqLevel7</tt></td>
</tr>

<tr>
<td>Returns current Interrupt Priority, 0 to 7</td>

<td><tt>ipac_irqGetLevel</tt></td>
</tr>

<tr>
<td>Enable interrupts from module</td>

<td><tt>ipac_irqEnable</tt></td>
</tr>

<tr>
<td>Disable interrupts from module</td>

<td><tt>ipac_irqDisable</tt></td>
</tr>

<tr>
<td>Returns current interrupt signal state</td>

<td><tt>ipac_irqPoll</tt></td>
</tr>

<tr>
<td>Sets LED indicator to Empty/Unused</td>

<td><tt>ipac_statUnused</tt></td>
</tr>

<tr>
<td>Sets LED indicator to Active</td>

<td><tt>ipac_statActive</tt></td>
</tr>

<tr>
<td>Resets this IP slot only</td>

<td><tt>ipac_slotReset</tt></td>
</tr>

</table>
</blockquote>

<p>
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. The use of level 7 is not recommended for
VxWorks systems as it may be non-maskable on some CPU boards; non-maskable
interrupts must not call any VxWorks OS routines. The <tt>ipac_irqGetLevel</tt>
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.</p>

<p>
The <tt>ipac_irqEnable</tt> command must be supported by all Carrier Drivers,
and must be called by any Module Driver that uses 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
<tt>ipac_irqDisable</tt> command is not necessarily supported by all carriers
however &ndash; the module driver must disable interrupts using the control
registers on the IP module itself if this is necessary. A Carrier Driver cannot
implement the <tt>ipac_irqDisable</tt> command with a call to the VxWorks
sysIntDisable() routine because this would stop any other devices which still
need this interrupt level from working.</p>

<p>
The <tt>ipac_slotReset</tt> command should only be implemented on carrier boards
that can reset IP slots individually without affecting any IP modules in
neighboring slots.  This command must not return until the reset process has
completed, so any driver using this may immediately proceed to reinitialize the
IP module as required.</p>

<h4>
Returns</h4>

<dl>
<dt>
<tt>int</tt></dt>

<dd>
<table BORDER=2>
<tr>
<th>Symbol/Value</th>

<th>Meaning</th>
</tr>

<tr>
<td>0</td>

<td>OK</td>
</tr>

<tr>
<td>S_IPAC_badAddress</td>

<td>No such carrier or slot</td>
</tr>

<tr>
<td>S_IPAC_notImplemented</td>

<td>Driver does not support that command</td>
</tr>
</table>

<p>Other values may also be returned depending on the Driver and command
used.</p></dd>
</dl>

<hr>


<h3>
<a NAME="ipmIntConnect"></a>ipmIntConnect</h3>

<p>
Connects a module driver Interrupt Service Routine to a particular interrupt
vector number.</p>

<pre>int ipmIntConnect (int carrier, int slot, int vecNum,
                   void (*routine)(int parameter), int parameter);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<tt>int carrier, int slot</tt></dt>

<dd>
Module identification &ndash; see <a href="#carrierSlot">above</a></dd>

<dt>
<tt>int vecNum</tt></dt>

<dd>
Interrupt vector number</dd>

<dt>
<tt>void (*routine)(int parameter)</tt></dt>

<dd>
Modules Interrupt Service Routine to be connected</dd>

<dt>
<tt>int parameter</tt></dt>

<dd>
Context parameter passed to Interrupt Service Routine</dd>
</dl>

<h4>
Description</h4>

<p>
Checks input parameters, then passes the request to the carrier driver routine.
If no carrier routine is provided it uses the devLib devConnectInterrupt()
routine instead. This is not quite a direct replacement for the VxWorks
intConnect() call; as well as providing the carrier and slot numbers the module
driver does not use the INUM_TO_IVEC(vecNum) macro but just passes the vector
number to this routine.</p>

<p>
The <tt>ipmIntConnect()</tt> routine allows a module driver to connect an ISR to
an interrupt vector from a particular IPAC module without independent of the
underlying OS or carrier. Some carrier drivers will need to maintain a private
interrupt dispatch table if the bus type (i.e. ISA) does not support interrupt
vectoring.</p>

<h4>
Returns</h4>

<dl>
<dt>
<tt>int</tt></dt>

<dd>
<table BORDER=2>
<tr>
<th>Symbol/Value</th>

<th>Meaning</th>
</tr>

<tr>
<td>0</td>

<td>OK</td>
</tr>

<tr>
<td>S_IPAC_badAddress</td>

<td>No such carrier, slot or vector</td>
</tr>
</table>

<p>Other values may also be returned depending on the Driver and vector
used.</p></dd>
</dl>

<hr>


<h3>
<a NAME="ipmReport"></a>ipmReport</h3>

Returns a printable string giving the status/settings of the given slot.

<pre>char *ipmReport(int carrier, int slot);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<tt>int carrier, int slot</tt></dt>

<dd>
Module identification &ndash; see <a href="#carrierSlot">above</a></dd>
</dl>

<h4>
Description</h4>

<p>
Generates a report string describing the given IPAC slot. If a module is
installed, it includes the manufacturer and model ID numbers. If the report
function is supported by the carrier driver this report string is appended.
This function is uses a static character array to hold the report string, thus
the value will be corrupted if two tasks use this routine simultaneously. The
string returned by the carrier driver's report routine will be clipped if
longer than IPAC_REPORT_LEN characters.</p>

<h4>
Returns</h4>

<dl>
<dt>
<tt>char *</tt></dt>

<dd>
Pointer to a static, printable string.</dd>
</dl>

<h4>
Sample Output</h4>

<blockquote>
<pre>C0 S0 : 0x23ae80/0x8d49 - M0 L3,3
C0 S1 : 0xB1/0x01 - M0 L4,5</pre>
</blockquote>

<p>
This string is made up of three parts. The first two elements before the colon
give the carrier and slot number of the slot. If a module is installed, the
manufacturer and model IDs follow as two hex numbers (2 digits each for Format-1
ID PROMS, 6+4 digits for Format-2 ID PROMS). Finally if the Carrier Driver
contains a report function it is called and the string it returns is appended
after a hyphen.</p>

<hr>


<h3>
<a NAME="ipcCheckId"></a>ipcCheckId</h3>

<p>
Check on the presence of an IPAC module at the given carrier and slot
number.</p>

<pre>int ipcCheckId(ipac_idProm_t *id);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<tt>ipac_idProm_t *id</tt></dt>

<dd>
Pointer to the module ID prom to be checked</dd>
</dl>

<h4>
Description</h4>

<p>
This routine must not be called if no module is present and an access to the id
pointer could trigger a bus error or SEGV. It checks that the ID Prom starts
with the format-1 "IPAC" or "IPAH" or format-2 "VITA4 " identifiers.</p>

<h4>
Returns</h4>

<dl>
<dt>
<tt>int</tt></dt>

<dd>
<table BORDER=2>
<tr>
<th>Symbol/Value</th>

<th>Meaning</th>
</tr>

<tr>
<td>0</td>

<td>OK</td>
</tr>

<tr>
<td>S_IPAC_badDriver</td>

<td>NULL pointer passed for id address</td>
</tr>

<tr>
<td>S_IPAC_noIpacId</td>

<td>IP Module identifier not found</td>
</tr>
</table></dd>
</dl>

<hr>


<h2>
<a NAME="section4"></a>4. IPAC Carrier Drivers</h2>

<h3>
<a NAME="VIPC310"></a>SBS VIPC310</h3>

<p>
This board is probably the simplest possible VME-based IPAC Carrier available.
A 3U VME card, it provides two IP slots (although it cannot support 32-bit
accesses to dual-slot IP modules), and allows no control over the slot
interrupt controllers from software. The base addresses for the card are set
using a series of jumpers on the board which select both the VME short I/O base
address (used for the IPAC ID Prom and Register spaces) and the VME Standard
base address (used for the IPAC Memory space if required). Additional jumpers
allow the size of the IPAC Memory to be selected. The interrupts are at
priority levels fixed by the hardware.</p>

<p>
The IPAC Carrier Driver for this board is found in the file <i>drvVipc310.c</i>
which implements the command <tt>ipacAddVIPC310</tt> to add a VIPC310 board to
the system, and provides the registrar routine <tt>vipc310Registrar</tt> to add
the above command to the iocsh and link the driver into a final IOC executable,
for which it must be listed in the IOC's .dbd file thus:</p>

<blockquote><pre>registrar(vipc310Registrar)</pre></blockquote>

<h4>
Configuration Command and Parameter</h4>

<pre>int ipacAddVIPC310(const char *cardParams);</pre>

<p>
The parameter string should comprise an integer (0x or 0X is now required for
hex) optionally followed by a comma and a second integer. The first number is
the I/O Base Address of the card in the VME A16 address space. The factory
default setting for the card gives an I/O Base Address of 0x6000, and this value
will be used if the string is empty or NULL. If supplied the second number in
the parameter string gives the size in Kbytes of the memory space allocated to
each IP module.</p>

<p>
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.</p>

<p>
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.</p>

<h4>
Configuration Examples</h4>

<dl>
<dt>
<tt>ipacAddVIPC310("0x6000")</tt></dt>

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

<dt>
<tt>ipacAddVIPC310("4096,512")</tt></dt>

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

<dt>
<tt>ipacAddVIPC310("0xfe00, 128")</tt></dt>

<dd>
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).</dd>
</dl>

<h4>
Interrupt Commands Supported</h4>

<p>
The board uses fixed interrupt levels, and provides no software control over
the interrupt generator. The only commands thus supported are a request of the
interrupt level associated with a particular slot and interrupt number, or to
enable interrupts by making sure the CPU's VMEbus interrupter is listening on
the necessary level.</p>

<blockquote>
<table BORDER=2>
<tr>
<th><tt>cmd</tt></th>

<th>Value Returned</th>
</tr>

<tr>
<td><tt>ipac_irqGetLevel</tt></td>

<td>slot interrupt level (1, 2, 4 or 5)</td>
</tr>

<tr>
<td><tt>ipac_irqEnable</tt></td>

<td>0 = OK</td>
</tr>

<tr>
<td>(other commands)</td>

<td>S_IPAC_notImplemented</td>
</tr>
</table>
</blockquote>

<hr>


<h3>
<a NAME="VIPC610"></a>SBS VIPC610</h3>

<p>
This board is a four-slot, 6U carrier, but otherwise very similar to the
VIPC310. A seperate driver is also included for the VIPC610-01 option which
changes the Interrupt Priority levels for the IP slots so they are equivalent
to a pair of VIPC310 carrier boards, different to the interrupt levels
for a standard VIPC610 board.</p>

<p>
The IPAC Carrier Drivers for both board versions are found in the file
<i>drvVipc610.c</i> which implements the commands <tt>ipacAddVIPC610</tt> and
<tt>ipacAddVIPC610_01</tt> for adding a VIPC610 board of the relevent type to
the system, and provides the registrar routine <tt>vipc610Registrar</tt> to add
the above commands to the iocsh and link the driver into a final IOC
executable, for which it must be listed in the IOC's .dbd file thus:</p>

<blockquote><pre>registrar(vipc610Registrar)</pre></blockquote>

<p>
<b>Warning:</b> As delivered by SBS the VIPC610 has IRQ0 of slot D connected to
the VMEbus level&nbsp;7 interrupt, and IRQ1 of slot D does not cause a VMEbus
interrupt at all.  Under VxWorks on the MC680x0 family a level&nbsp;7 interrupt
level may only be connected to a service routine that does not make any calls
to VxWorks routines.  Thus with a VIPC610 board slot D should not be used for
modules that generate interrupts.  The VIPC610-01 board option is free of this
problem.</p>

<h4>
Configuration Commands and Parameter</h4>

<pre>int ipacAddVIPC610(const char *cardParams);
int ipacAddVIPC610_01(const char *cardParams);</pre>

<p>
The parameter string should comprise an integer (0x or 0X is now required for
hex) optionally followed by a comma and a second integer. The first number is
the I/O Base Address of the card in the VME A16 address space. The factory
default setting for the card gives an I/O Base Address of 0x6000, and this value
will be used if the string is empty or NULL. If supplied the second number in
the parameter string gives the size of the memory space in Kbytes allocated to
each IP module.</p>

<p>
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.</p>

<p>
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.</p>

<h4>
Configuration Examples</h4>

<dl>
<dt>
<tt>ipacAddVIPC610("0x6000")</tt></dt>

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

<dt>
<tt>ipacAddVIPC610_01("4096,128")</tt></dt>

<dd>
Here the I/O base is set to 4096 = 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.</dd>

<dt>
<tt>ipacAddVIPC610("0X7000,1024")</tt></dt>

<dd>
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).</dd>
</dl>

<h4>
Interrupt Commands Supported</h4>

<p>
The board uses fixed interrupt levels, and provides no software control over
the interrupt generator. The only commands thus supported are a request of the
interrupt level associated with a particular slot and interrupt number, or to
enable interrupts by making sure the CPU's VMEbus interrupter is listening on
the necessary level. Note that the VIPC610-01 uses different interrupt levels
to the straight VIPC610, you must use the correct driver!</p>

<blockquote>
<table BORDER=2>
<tr>
<th><tt>cmd</tt></th>

<th>Value Returned</th>
</tr>

<tr>
<td><tt>ipac_irqGetLevel</tt></td>

<td>slot interrupt level</td>
</tr>

<tr>
<td><tt>ipac_irqEnable</tt></td>

<td>0 = OK</td>
</tr>

<tr>
<td>(other commands)</td>

<td>S_IPAC_notImplemented</td>
</tr>
</table>
</blockquote>

<hr>


<h3>
<a NAME="VIPC616"></a>SBS VIPC616</h3>

<p>
This board is a four-slot, 6U carrier, but otherwise very similar to the
VIPC310. A seperate driver is also included for the VIPC616-01 option which
changes the Interrupt Priority levels for the IP slots so they are equivalent
to a pair of VIPC310 carrier boards, different to the interrupt levels
for a standard VIPC616 board.</p>

<p>
The only differences between this carrier and the VIPC610 relate to the VME
addressing capabilities, the VIPC616 supports access to memory IP modules in
the VME A32 address space. It is possible to use the VIP610 driver to control a
VIPC616 board, but the use of this specific driver is recommended. This driver
should also be used for the VIPC618 carrier which is schematically identical to
the VIPC616 but uses different I/O connectors for the IP module signals.</p>

<p>
The IPAC Carrier Drivers for both board versions are found in the file
<i>drvVipc616.c</i> which implements the commands <tt>ipacAddVIPC616</tt> and
<tt>ipacAddVIPC616_01</tt> to add a VIPC616 board of the relevent type to the
system, and provides the registrar routine <tt>vipc616Registrar</tt> to add the
above commands to the iocsh and link the driver into a final IOC executable,
for which it must be listed in the IOC's .dbd file thus:</p>

<blockquote><pre>registrar(vipc616Registrar)</pre></blockquote>

<p>
<b>Warning:</b> As delivered by SBS the VIPC616 has IRQ0 of slot D connected to
the VMEbus level&nbsp;7 interrupt, and IRQ1 of slot D does not cause a VMEbus
interrupt at all.  Under VxWorks on the MC680x0 family a level&nbsp;7 interrupt
level may only be connected to a service routine that does not make any calls
to VxWorks routines.  Thus with a VIPC616 board slot D should not be used for
modules that generate interrupts.  The VIPC616-01 board option is free of this
problem.</p>

<h4>
Configuration Commands and Parameter</h4>

<pre>int ipacAddVIPC616(const char *cardParams);
int ipacAddVIPC616_01(const char *cardParams);</pre>

<p>
The parameter string should comprise an integer (0x or 0X is now required for
hex) optionally followed by a comma and a second integer (with 0x/0X if hex),
and then possibly another comma and a third integer. The first number is the I/O
Base Address of the card in the VME A16 address space. The factory default
setting for the card gives an I/O Base Address of 0x6000, and this value will be
used if the string is empty or NULL. If only the I/O Base Address given, the IP
modules are not allocated any memory.</p>

<p>
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.</p>

<p>
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.</p>

<h4>
Configuration Examples</h4>

<dl>
<dt>
<tt>ipacAddVIPC616("")</tt></dt>

<dd>
This indicates that the board is configured as delivered by the manufacturer,
with the I/O base set to 0x6000 and the memory base address to 0xd0000000 in
the VME A32 space, with 8MB of memory space available for each slot.

<dt>
<tt>ipacAddVIPC616("0x9000")</tt></dt>

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

<dt>
<tt>ipacAddVIPC616_01("4096,0x8000000")</tt></dt>

<dd>
Here the I/O base is set to 4096 = 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.</dd>

<dt>
<tt>ipacAddVIPC616("0x7000,0x700000,1024")</tt></dt>

<dd>
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).</dd>
</dl>

<h4>
Interrupt Commands Supported</h4>

<p>
The board uses fixed interrupt levels, and provides no software control over
the interrupt generator. The only commands thus supported are a request of the
interrupt level associated with a particular slot and interrupt number, or to
enable interrupts by making sure the CPU's VMEbus interrupter is listening on
the necessary level. Note that the VIPC616-01 uses different interrupt levels
to the straight VIPC616, you must use the correct driver!</p>

<blockquote>
<table BORDER=2>
<tr>
<th><tt>cmd</tt></th>

<th>Value Returned</th>
</tr>

<tr>
<td><tt>ipac_irqGetLevel</tt></td>

<td>slot interrupt level</td>
</tr>

<tr>
<td><tt>ipac_irqEnable</tt></td>

<td>0 = OK</td>
</tr>

<tr>
<td>(other commands)</td>

<td>S_IPAC_notImplemented</td>
</tr>
</table>
</blockquote>

<hr>


<h3>
<a NAME="TVME200"></a>Tews TVME-200</h3>

<p>
This board is a four-slot, 6U carrier which is also sold by SBS as the VIPC626
and was also available from XYCOM VME.  The configuration of the board is much
simpler than the VIPC boards it replaces as there are only 6 rotary hexadecimal
switches which completely configure the board.  There are also a pair of
registers provided for each slot, which allow the interrupt levels to be read
and configured in software and permit individual slots to be reset.</p>

<p>
It is possible to use the VIP610 or VIPC616 drivers to control an appropriately
configured TVME-200 board, but the use of this specific driver is strongly
recommended if possible.</p>

<p>
The IPAC Carrier Driver is found in the file <i>drvTvme200.c</i> which
implements the command <tt>ipacAddTVME200</tt> that registers a TVME-200 board
with drvIpac. It also exports the registrar routine <tt>tvme200Registrar</tt> to
add the above command to the iocsh and link the driver into a final IOC
executable, for which it must be listed in the IOC's .dbd file thus:</p>

<blockquote><pre>registrar(tvme200Registrar)</pre></blockquote>


<h4>
Configuration Commands and Parameter</h4>

<pre>int ipacAddTVME200(const char *cardParams);</pre>

<p>
The parameter string must contain exactly 6 hexadecimal digits (without any
leading 0x or 0X) which are the settings of the six rotary switches on the
board, in order from S1 through S6. The board's silk-screen printing shows the
possible values and meaning for each switch position. The carrier initialization
routine checks the switch settings for legality and will return an error if it
finds an unsupported (undocumented) setting, as there are some combinations
of switch settings that are reserved or not permitted.</p>

<h4>
Configuration Examples</h4>

<dl>
<dt>
<tt>ipacAddTVME200("6010D0")</tt></dt>

<dd>
This indicates that the board is configured as delivered by the manufacturer,
with the I/O base set to 0x6000, interrupt levels matching the VIPC610 or 616,
and all module memory spaces disabled.

<dt>
<tt>ipacAddTVME200("100580")</tt></dt>

<dd>
This indicates that the board has its I/O base address at 0x1000, all interrupts
are disabled, and each IP module is allocated 2MB of memory space with the
memory base address in VME A24 space starting at 0x800000.

<dt>
<tt>ipacAddTVME200("602FB0")</tt></dt>

<dd>
Here the I/O base address is set to 0x6000, and interrupts are configured to
match a pair of VIPC310 boards. Each IP module is allocated 8MB of VME A32
memory space starting at 0xB0000000, which puts IP module A's memory at
0xB0000000, module B at 0xB0800000, module C at 0xB1000000 and D at
0xB1800000. This particular setting is commonly used at APS.</dd>

</dl>

<h4>
Interrupt Commands Supported</h4>

<p>
The board provides a configuration switch to select from 5 different fixed VME
interrupt level configurations, but it also provides software control over the
interrupt generator which allows these levels to be changed under program
control as needed. The commands supported therefore include the ability to get
or set the interrupt level, and also to poll whether the interrupt line is
currenly active or not. A control register bit also permits each slot to be
reset individually.</p>

<blockquote>
<table BORDER=2>
<tr>
<th><tt>cmd</tt></th>

<th>Value Returned</th>
</tr>

<tr>
<td><tt>ipac_irqLevel<i>N</i></tt></td>

<td>0 = OK</td>
</tr>

<tr>
<td><tt>ipac_irqGetLevel</tt></td>

<td>slot interrupt level</td>
</tr>

<tr>
<td><tt>ipac_irqEnable</tt></td>

<td>0 = OK</td>
</tr>

<tr>
<td><tt>ipac_irqPoll</tt></td>

<td>&gt;0 if the interrupt line is active, else 0</td>
</tr>

<tr>
<td><tt>ipac_slotReset</tt></td>

<td>0 = OK</td>
</tr>

<tr>
<td>(other commands)</td>

<td>S_IPAC_notImplemented</td>
</tr>
</table>
</blockquote>

<hr>
<h3>
<a NAME="ATC40"></a>SBS ATC40</h3>

<p>
The SBS ATC40 is an IP carrier board for the ISAbus, which is a little-endian
architecture unlike the VMEbus. Providing support for this board has required
some changes to the drvIpac software which are described in the
<a href="#Bus Issues">Bus Issues</a> section above. Unless similar precautions
are taken when writing module drivers these will not be compatible with
little-endian systems. This carrier driver was written by
<a href="mailto:peregrine@lanl.gov">Peregrine McGehee</a> and
<a href="mailto:johill@lanl.gov">Jeff Hill</a>, who should be approached
directly for support. Note that the carrier driver will probably only run on an
Intel CPU, and has not been tested with recent drvIpac releases.</p>

<p>
The registrar entry for this driver should be:</p>

<blockquote><pre>registrar(atc40Registrar)</pre></blockquote>

<p>
The configuration command is shown below.  See the source code for the format
of the parameter string.</p>

<blockquote><pre>int ipacAddATC40(const char *cardParams);</pre></blockquote>

<hr>


<h3>
<a NAME="MVME162"></a>Motorola MVME162 and MVME172</h3>

<p>
The Motorola MVME162 and MVME172 CPU boards provide either two or four IP slots
in addition to the MC68040 CPU, memory and I/O. Slot pairs can be used with
32-bit dual-slot IP modules, and the IPIC chip which controls the interface
supports all of the IPAC Driver interrupter commands. This carrier driver can
be used with either board; non-existant slots will always appear to be
empty.</p>

<p>
When this CPU board is used the IPAC carrier driver <i>drvIpMv162.c</i> can
control the IP slots on the board. It implements the command
<tt>ipacAddMVME162</tt> to add the MVME162 or MVME172 carrier to the system,
and provides the registrar routine <tt>mv162ipRegistrar</tt> to add the above
command to the iocsh and link the driver into a final IOC executable, for which
it must be listed in the IOC's .dbd file thus:</p>

<blockquote><pre>registrar(mv162ipRegistrar)</pre></blockquote>

<p>
The carrier initialisation routine has the following additional return-code
meanings (see also <a href="#ipacInitialise">ipacInitialise()</a> above):</p>

<blockquote>
<table BORDER=2>
<tr>
<td><b>Symbol/Value</b></td>

<td><b>Meaning</b></td>
</tr>

<tr>
<td>S_IPAC_tooMany</td>

<td>IpMv162 carrier already registered</td>
</tr>

<tr>
<td>S_IPAC_badDriver</td>

<td>IPIC chip not found</td>
</tr>

<tr>
<td>S_IPAC_badAddress</td>

<td>Parameter string error, or address not reachable</td>
</tr>
</table>
</blockquote>

<h4>
Configuration Commands and Parameter</h4>

<pre>int ipacAddMVME162(const char *cardParams)</pre>

<p>
The parameter string is used to initialise the IPIC registers which allow
detailed control of several settings for each slot. The string consists of a
series of single characters to determine the slot and setting to be controlled
and one or more numeric parameters for each setting. The string is parsed
sequentially from left to right, and the characters and their parameters have
the following meanings:</p>

<dl>
<dt>
<tt>R</tt></dt>

<dd>
If used this must be the first character of the string, and will cause a
hardware reset pulse to be sent to all the IP modules.  This is useful if any
module is found to need a hardware reset on a VxWorks soft reboot.</dd>

<dt>
<tt>A</tt>, <tt>B</tt>, <tt>C</tt> and <tt>D</tt></dt>

<dd>
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.</dd>

<dt>
<tt>l=<i>level1[</i>,<i>level2]</i></tt></dt>

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

<dt>
<tt>m=<i>base</i>,<i>size</i></tt></dt>

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

<dt>
<tt>r=<i>recovery</i></tt></dt>

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

<dt>
<tt>w=<i>width</i></tt></dt>

<dd>
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
<tt>w=16</tt> 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
<tt>w=8</tt> 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 <tt>w=32</tt> 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.</dd>
</dl>

<p>
Other characters will be ignored without affecting the parsing of the remainder
of the parameter string.</p>

<h4>
Configuration Example</h4>

<blockquote>
<pre>ipacAddMVME162("A:m=0x90000000,1024 l=5,3 w=8 r=2 B:l=2")</pre>
</blockquote>

<p>
The above example initialises slots 0 and 1 only &ndash; slots 2 and 3 are not
used or their modules require register and ID Prom access only in this
particular application.</p>

<p>
Slot 0 is set up for a slow (recovery time 2&micro;s) memory board with
1&nbsp;Mbyte of 8-bit wide RAM, addressed at 0x90000000 and with interrupt
priorities set for levels 5 and 3.</p>

<p>
Slot 1 has no memory space, and just a single interrupt at priority
level&nbsp;2.</p>

<h4>
Interrupt Commands Supported</h4>

<p>
The IPIC chip allows a lot of control over the IP interrupters, thus all
commands perform the requested action. The <tt>ipmIrqCmd</tt> return values for
the commands are:</p>


<blockquote>
<table BORDER=2>
<tr>
<th><tt>cmd</tt></th>

<th>Value Returned</th>
</tr>

<tr>
<td><tt>ipac_irqGetLevel</tt></td>

<td>current slot interrupt level</td>
</tr>

<tr>
<td><tt>ipac_irqPoll</tt></td>

<td>&gt;0 if the interrupt line is active, else 0</td>
</tr>

<tr>
<td>Other ipac_irq commands</td>

<td>0 = OK</td>
</tr>

<tr>
<td><tt>Other commands</tt></td>

<td>S_IPAC_notImplemented</td>
</tr>
</table>
</blockquote>

<hr>


<h3>
<a NAME="AVME9660"></a>Acromag AVME-9660/9668/9670</h3>

<p>
These boards are four-slot, 6U VME carriers, two of which were once sold by
Xycom as the XVME-9660/9670. On the 9660 board the IP module signal wiring is
brought out through front panel connectors, whereas the 9670 boards make signal
wiring available through the VME64x P2 and P0 connectors. The AVME-9668 is like
the 9660 but can operate IP modules at 8MHz or 32MHz, whereas the other boards
only support 8MHz operation. A single bank of jumpers provides the only hardware
configuration, setting the base address of the board in VME A16 space; module
memory locations in VME A24 space and the module clock speeds for the 9668 are
configured in software using the board registers.</p>

<p>
The IPAC Carrier driver is found in the file <i>drvXy9660.c</i> and implements
the commands <tt>ipacAddAvme96XX</tt> and <tt>ipacAddXy9660</tt> that register a
single carrier board (of any of the supported models) with drvIpac. The driver
also exports a registrar routine <tt>xy9660Registrar</tt> that adds the above
command to the iocsh and will link the driver into a final IOC executable, for
which it must be listed in the IOC's .dbd file thus:</p>

<blockquote><pre>registrar(xy9660Registrar)</pre></blockquote>

<h4>
Configuration Commands and Parameter</h4>

<pre>int ipacAddXy9660(const char *cardParams);
int ipacAddAvme96XX(const char *cardParams);</pre>

<p>
The parameter string starts with a hex number (a leading 0x is optional) which
sets the I/O base address of the card in the VME A16 address space (the factory
default is 0x0000). Next must come a comma, followed by the VME interrupt level
(0 through 7, although 0 means all interrupts are disabled) to be used for this
carrier (all module interrupts share the same interrupt level from this
board).</p>

<p>
A letter <tt>R</tt> may appear at this point, which causes a carrier soft reset
to be generated before any further configuration occurs.</p>

<p>
Finally if any module drivers need to access the memory space on their module,
the relevent slots must have their memory size and base address configured,
which is done like this for each slot:</p>

<dl>
<dt>
<tt><i>slot</i> = <i>size</i>, <i>address</i></tt></dt>

<dd>
Configures one slot on the card, setting the size and base address of the slot's
memory space in VME A24 space. The <i>slot</i> parameter is one of the letters
<tt>A</tt> through <tt>D</tt> and selects which slot is to be configured. The
<i>size</i> is a single digit <tt>1</tt>, <tt>2</tt>, <tt>4</tt> or <tt>8</tt>
which gives the memory size to be used, expressed in MegaBytes. The
<i>address</i> is a 6-digit hexadecimal number (a leading <tt>0x</tt> is
optional) which must be compatible with the selected memory size. Slots may be
configured in any order, but cannot be programmed to overlap.</dd>

</dl>

<h4>
Configuration Examples</h4>

<blockquote>
<pre>ipacAddXy9660("0x6000,4 R")</pre>
</blockquote>

<p>
This indicates that the carrier board has its I/O base set to A16:6000 and that
it generates interrupts on VME IRQ4. None of the slots are configured for
memory, and modules are reset at initialization.</p>

<blockquote>
<pre>ipacAddAvme96XX("C000,3 A=2,800000 C=1,A00000")</pre>
</blockquote>

<p>
The carrier is at A16:C000 and generates level 3 interrupts. Slot A is
configured for 2MB of memory space at A24:800000 and Slot C for 1MB of memory
space at A24:A00000.</p>

<hr>


<h3>
<a NAME="Hy8002"></a>Hytec 8002/8004</h3>

<p>
These boards are 6U VME64x carrier cards that provide four single-width IP
slots. Their User Manuals imply that double-wide slots are supported by the
hardware, but this driver does not implement that configuration. Geographical
addressing can be used to set the board address when installed in a VME64x
crate, or jumpers can be used to set the board address when installed in an
older chassis. The 8004 model can control the IP clock speeds of the slots
independently, while the 8002 supports clocking all slots at either 8MHz or
32MHz. The IP memory base address can be selected using geographic addressing,
or can be directly programmed by the driver. The board supports a single VME
interrupt reqest level which is shared by all module interrupts.</p>

<p>
The IPAC carrier driver is found in the file <i>drvHy8002.c</i> and implements
two commands <tt>ipacAddHy8002</tt> and <tt>ipacHy8002CarrierInfo</tt> which
register a single carrier board (of either model) and print out various board
model and serial numbers respectively. The driver also exports a registrar
routine <tt>Hy8002Registrar</tt> that adds the commands to the iocsh and will
link the driver into a final IOC executable, for which it must be listed in the
IOC's .dbd file thus:</p>

<blockquote>
<pre>registrar(Hy8002Registrar)</pre>
</blockquote>

<h4>
Configuration Commands and Parameter</h4>

<pre>int ipacAddHy8002(const char *cardParams);</pre>

<p>
The parameter string starts with two decimal integers separated by a comma,
which give the board's VME slot number (0 through 21) and the VME interrupt
level to be used (0 through 7, 0 means interrupts are disabled). If a VME64x
backplane is not being used to provide geographical addressing information, the
slot number parameter must match the value set in jumpers J6 through J10, with
J6 being the LSB and an installed jumper giving a 1 bit.</p>

<p>
After the above mandatory parameters, any of the following optional parameters
may appear in any order. Space characters cannot be used on either side of the
equals sign:</p>

<dl>
<dt>
<tt>IPMEM=<i>size</i></tt></dt>

<dd>
Sets the extent of the memory space allocated for each IP slot. The <i>size</i>
parameter is a single digit <tt>1</tt>, <tt>2</tt>, <tt>4</tt> or <tt>8</tt>
which gives the memory size to be used, expressed in MegaBytes. If this
parameter is not provided the default value of 1 will be used.</dd>

<dt>
<tt>MEMBASE=<i>address</i></tt></dt>

<dd>
Specifies the top 16 bits of the base address of the A32 memory area to be used
for IP slot memory space, overriding the jumper-selected or VME64x geographical
address that will be used if this parameter is not provided. The <i>address</i>
string should be a decimal integer or a number hex with a leading <tt>0x</tt>.
The resulting base address must be a multiple of 4 times the slot memory size;
an error message will be printed if this restriction is not met.</dd>

<dt>
<tt>IPCLK=<i>frequency</i></tt></dt>

<dd>
Specifies the frequency in MHz of the IP clock passed to all slots. The
<i>frequency</i> parameter must be either <tt>8</tt> or <tt>32</tt>. If not
specified for a 8002 carrier the IP clock will default to 8MHz, while for a 8004
carrier the driver will then configure each slot individually based on
information from the ID prom of the module installed; specifying this parameter
for an 8004 board overrides the module's configuration for all slots.</dd>

<dt>
<tt>ROAK=<i>release</i></tt></dt>

<dd>
This parameter controls when an 8004 carrier board will releases the interrupt
request to the VMEbus. Giving <i>release</i> as <tt>1</tt> will cause the
request to be released by the VME Interrupt Acknowledge cycle (ROAK protocol).
If <i>release</i> is given as <tt>0</tt> or the parameter is not specified at
all, the interrupt request will be released by the module's interrupt service
routine clearing the module's reason for the interrupt request (RORA protocol)
or disabling the interrupt using <tt>ipmIrqCmd(<i>carrier</i>, <i>slot</i>,
<i>irqn</i>, ipac_irqDisable)</tt>.</dd>

</dl>

<h4>
Configuration Examples</h4>

<blockquote>
<pre>ipacAddHy8002("3,2")</pre>
</blockquote>

<p>
In this configuration the board is in slot 3 of a VME64x crate, or jumpers are
installed in positions J6 and J7. Module interrupts will use VMEbus level 2. IP
slots will get 1MB of memory space in a block starting at A32:0x00c00000, and
the default IP clock frequency as described above.</p>

<blockquote>
<pre>ipacAddHy8002("3,2 IPMEM=2, MEMBASE=0x9000,IPCLCK=32 ROAK=1")</pre>
</blockquote>

<p>
This modifies the above configuration to give each slot 2MB of memory space in
the block starting at A32:0x90000000, drives all IP clocks at 32MHz, and uses
the ROAK protocol for releasing interrupt requests.</p>

<hr>


<h2>
<a NAME="section5"></a>5. Interface to IPAC Carrier Drivers</h2>

<p>
Writing a new Carrier Driver is quite simple, and requires just three
subroutines to be produced (the report function is optional). The driver will
need some of the definitions in the <i>drvIpac.h</i> file.</p>

<pre>#include "drvIpac.h"</pre>

<p>
All routines must be re-entrant, and no static variables should be used unless
(like the mv162) only one carrier board of this type is possible in a
particular system. In this case re-entrancy is still necessary, but static
variables may be used to hold information about the carrier, provided these are
protected from simultaneous updates by different tasks.</p>

<p>
The sole interface between the Carrier Driver and the IPAC driver is through the
<tt>ipac_carrier_t</tt> typedef structure given in the header file. Note that
the structure has changed slightly in different IPAC versions with the addition
of the carrier parameter to the initialise() routine, and by adding the optional
intConnect() and moduleProbe() routines. The structure is defined as
follows:</p>

<blockquote>
<pre>typedef struct {
    char *carrierType;                 <i>/* String describing carrier board type */</i>
    epicsUInt16 numberSlots;           <i>/* Number of IPAC devices this carrier can hold */</i>
    int (*initialise)(char *cardParams, void **cPrivate, epicsUInt16 carrier);
                                       <i>/* Initialise carrier and return *cPrivate */</i>
    char *(*report)(void *cPrivate, epicsUInt16 slot);
                                       <i>/* Return string giving status of this slot */</i>
    void *(*baseAddr)(void *cPrivate, epicsUInt16 slot, ipac_addr_t space);
                                       <i>/* Return base addresses for this slot */</i>
    int (*irqCmd)(void *cPrivate, epicsUInt16 slot, epicsUInt16 irqNumber,
                  ipac_irqCmd_t cmd);  <i>/* Interrupt control */</i>
    <i>/* The remaining routines are optional. Some drvIpac routines may call</i>
    <i> * devLib if these routines are NULL or not provided. */</i>
    int (*intConnect)(void *cPrivate, epicsUInt16 slot, epicsUInt16 vecNum,
                      void (*routine)(int parameter), int parameter);
                                       <i>/* Connect routine to interrupt vector */</i>
    int (*moduleProbe)(void *cPrivate, epicsUInt16 slot);
                                       <i>/* Return 0 if reading ID Prom would Bus Error */</i>
} ipac_carrier_t;</pre>
</blockquote>

<p>
The first two structure members provide fixed information about the carrier to
the IPAC driver. <tt>carrierType</tt> is a string which is printed by the
report function to identify the type of carrier board, and <tt>numberSlots</tt>
indicates how many IPAC slots this particular type of carrier provides.</p>

<p>
The remaining structure members are function pointers to the routines which
control the carrier board. The <tt>cPrivate</tt> 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
<tt>cPrivate</tt> 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.</p>

<p>
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 <tt>slot</tt> and <tt>irqNumber</tt> parameters
before calling the Carrier Driver routine, so these values can be used without
having to check them.</p>

<p>
The intConnect() function pointer may be set to NULL if the devLib routine
devConnectInterrupt() provides all the functionality needed to install an
interrupt vector &ndash; carriers that are not interfaced through the EPICS
devLib routines will need to provide this routine.</p>

<p> The moduleProbe() function pointer may be set to NULL if the devLib routine
devReadProbe() can be used to detect the presence of a module by probing the ID
Prom space. Carriers that are not interfaced through the EPICS devLib routines
will need to provide this routine, which indicates whether it is safe to read
the ID Prom space of the given slot. Returning zero means that there is no
module present in that slot and accessing the ID Prom is prohibited; returning a
non-zero value permits the IPAC Driver routines to check for the presence of a
module by reading from the ID Prom and looking for a valid IPAC header. If the
carrier hardware is designed such that reading the ID PROM of an empty slot
never triggers a VME Bus Error or segment violation, this routine can just
return 1 for all inputs.</p>

<p>
The simplest way to write a carrier driver is to copy the VIPC610 or TVME200
driver and modify it for the new board type. The TVME200 driver can configure
some aspects of each IPAC slot separately, while the VIPC610 board has no
programmable registers at all and thus provides the simplest possible example of
a carrier driver.</p>

<hr>


<address>
Andrew Johnson
<a href="mailto:anj@aps.anl.gov">&lt;anj@aps.anl.gov&gt;</a></address>

</body>
</html>