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="IndustryPack, vxWorks, EPICS, GreenSpring">
   <meta name="Version" content="$Id: drvIpac.html,v 1.10 2003-11-14 00:22:44 anj Exp $">
   <title>drvIpac - Industry Pack Driver</title>
</head>
<body bgcolor="#FFFFFF">

<center>
<h1>
drvIpac - Industry Pack Driver</h1>

Version 2.6

<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="#ipacReport">ipacReport</a></li>

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

<li>
<a href="#section3">Calls for use by IPAC Module 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>
</ul></li>

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

<ul>
<li>
<a href="#VIPC310">GreenSpring VIPC310</a></li>

<li>
<a href="#VIPC610">GreenSpring VIPC610</a></li>

<li>
<a href="#VIPC616">GreenSpring VIPC616</a></li>

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

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

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

See also the following Module Drivers which use drvIpac:

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

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

<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 vxWorks, 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 
<a href="http://www.jach.hawaii.edu/UKIRT/home.html">UKIRT</a> 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.
On VMEbus, carrier drivers are available for the 
<a href="http://www.greenspring.com/">GreenSpring</a> VIPC310, 610 and 616
boards, and a driver for the <a href="http://www.mcg.mot.com/">Motorola</a>
MVME162 that also works on the MVME172.  On ISAbus the GreenSpring ATC40
carrier is now supported by a driver from Jeff Hill.</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 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.</p>

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

<p>
From version 2.0 onwards the drvIpac subsystem has been separated from the
CANbus driver but provided within an EPICS &lt;supporttop&gt; application which
can also be used to build IPAC module drivers. To install and use the the ipac
support, obtain a copy of the tar file or (if you have remote CVS permissions
at APS) export the software from the CVS repository where it resides as
<tt>epics/modules/bus/ipac</tt> - CVS tags of the form `<b><tt>V2-1</tt></b>'
mark the particular file versions required for each release. These instructions
assume you already have EPICS R3.14.x installed and built (this software should
work with EPICS R3.14.3 and later). Two 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>
Run gnumake in the top level directory.</li>
</ol>

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

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

<p>
From version 2-1 this software supports little-endian as well as big-endian
busses, and provides a means of isolating module drivers from some of the
differences between interrrupt handling on different busses.</p>

<p>
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 <tt>short</tt>
instead of <tt>char</tt> and removing the `padding' char members that separate
the registers (this change has been made to the <tt>ipac_idProm_t</tt>
structure which is declared in <i>drvIpac.h</i>). This done the other changes
are generally minor, usually consisting of masking 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>

<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. This
header <b><tt>#include</tt></b>s the vxWorks ANSI header file <i>types.h</i>
thus a <b><tt>-I</tt></b> option to the C pre-processor must be used to
indicate the location of the vxWorks header files.</p>

<p>If it is necessary to build a copy of the driver for use without EPICS, the
<i>drvIpac.c</i> file should be compiled with the <b><tt>-DNO_EPICS</tt></b>
compiler switch to disable the EPICS-specific code.</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 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 (<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 vxWorks (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>

<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(NULL, "");
ipacAddCarrier(&amp;vipc310, "0x6800");</pre>
</blockquote>

<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. Calls for use by IPAC Module Drivers</h2>

<p>
The routines documented below are provided for use by the module drivers
which use the services of the generic IPAC driver. In general it is expected
that these routines will only be used at initialisation time. The module
driver should be informed by other means which carrier and slot the particular
IPAC module it is to control is installed in, although it should be possible
to search each carrier and slot number in turn for the 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(ushort_t carrier, ushort_t slot, ipac_addr_t space);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<a NAME="carrierSlot"></a><tt>ushort_t 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 by calling <tt>ipacAddCarrier</tt>.</dd>

<dt>
<tt>ushort_t 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 - the VIPC310 and MVME172 provide 2, the VIPC610, VIPC616, ATC40 and
MVME162 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(ushort_t carrier, ushort_t slot);</pre>

<h4>
Parameters</h4>

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

<dd>
Module identification - see <a href="#carrierSlot">above</a></dd>
</dl>

<h4>
Description</h4>

<p>
Does a quick check to make sure the carrier and slot numbers are legal,
probes the IDprom space to ensure an IPAC is installed, and checks that
the IDprom starts with an "IPAC" or "IPAH" identifier.</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>"IPAC" 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(ushort_t carrier, ushort_t slot,
                uchar_t manufacturerId, uchar_t modelId);</pre>

<h4>
Parameters</h4>

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

<dd>
Module identification - see <a href="#carrierSlot">above</a></dd>

<dt>
<tt>uchar_t manufacturerId</tt></dt>

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

<dt>
<tt>uchar_t 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>

<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>"IPAC" or "IPAH" identifiers 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(ushort_t carrier, ushort_t slot,
              ushort_t irqNumber, ipac_irqCmd_t cmd);</pre>

<h4>
Parameters</h4>

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

<dd>
Module identification - see <a href="#carrierSlot">above</a></dd>

<dt>
<tt>ushort_t 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 0 or 1 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 (non-maskable)</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>
</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. Level 7 is not recommended within vxWorks
as it is non-maskable, and may only be used for an ISR that does not call any
vxWorks 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 - 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>

<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 (ushort_t carrier, ushort_t slot, ushort_t vecNum, 
                   void (*routine)(int parameter), int parameter);</pre>

<h4>
Parameters</h4>

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

<dd>
Module identification - see <a href="#carrierSlot">above</a></dd>

<dt>
<tt>ushort_t 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 standard vxWorks intConnect()
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>
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.</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(ushort_t carrier, ushort_t slot);</pre>

<h4>
Parameters</h4>

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

<dd>
Module identification - 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 single internal static character array to hold
the report string, thus the value will be corrupted if two tasks use this
routine simultaneously.</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 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. Finally if the
Carrier Driver contains a report function it is called and the string it
returns is appended after the hyphen.</p>

<hr>


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

<h3>
<a NAME="VIPC310"></a>GreenSpring 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 a hexadecimal number (an 0x or 0X at the
start is optional) optionally followed by a comma and a decimal 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("1000,512")</tt></dt>

<dd>
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.</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>GreenSpring 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/GreenSpring 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 a hexadecimal number (an 0x or 0X at the
start is optional) optionally followed by a comma and a decimal 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("1000,128")</tt></dt>

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

<dt>
<tt>ipacAddVIPC610("7000,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>GreenSpring 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(vipc610Registrar)</pre></blockquote>

<p>
<b>Warning:</b> As delivered by SBS/GreenSpring 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 a hexadecimal number (an 0x or 0X at the
start is not required) optionally followed by a comma and another hexadecimal
number, and then possibly another comma and a decimal 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.</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("1000,8000000")</tt></dt>

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

<dt>
<tt>ipacAddVIPC616("7000,700000,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="ATC40"></a>GreenSpring ATC40</h3>

<p>
The GreenSpring 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 source file
<i>drvIpac/drvAtc40.c</i> will only compile for Pentium CPUs.</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 - 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 calls</td>

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

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

<blockquote>
<pre>typedef struct {
    char *carrierType;                 <i>/* String describing carrier board type */</i>
    ushort_t numberSlots;              <i>/* Number of IPAC devices this carrier can hold */</i>
    int (*initialise)(char *cardParams, void **cPrivate, ushort_t carrier);
                                       <i>/* Initialise carrier and return *cPrivate */</i>
    char *(*report)(void *cPrivate, ushort_t slot);
                                       <i>/* Return string giving status of this slot */</i>
    void *(*baseAddr)(void *cPrivate, ushort_t slot, ipac_addr_t space);
                                       <i>/* Return base addresses for this slot */</i>
    int (*irqCmd)(void *cPrivate, ushort_t slot, ushort_t irqNumber,
                  ipac_irqCmd_t cmd);  <i>/* Interrupt control */</i>
    int (*intConnect)(void *cPrivate, ushort_t slot, ushort_t vecNum,
                      void (*routine)(int parameter), int parameter);
                                       <i>/* Connect routine to interrupt vector */</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 intConnect() function pointer may be set to NULL if the standard vxWorks
intConnect() provides all the funtionality needed to install an interrupt
vector - this will probably only be needed for ISA bus carriers.</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 with
confidence.</p>

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

<hr>


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

</body>
</html>