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, SBS">
   <meta name="Version" content="$Id$">
   <title>drvIpac - Industry Pack Driver</title>
</head>
<body bgcolor="#FFFFFF">

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

Version 2.9

<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="#ipacLatestCarrier">ipacLatestCarrier</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">SBS VIPC310</a></li>

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

<li>
<a href="#VIPC616">SBS 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="#XVME9660">Xycom XVME-9660/9670</a></li>
</ul></li>

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

See also the following Module Drivers which are included with drvIpac:

<ul>

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

<li>
<a href="tyGSOctal.html">SBS Octal Serial IP module (RS232, RS422,
RS485)</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 completely without altering any of its interfaces.</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, 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.4 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>
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 to include 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>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. 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>short</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>

<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, ipacAddCarrier() will always increment
its internal carrier number on every call, thus a carrier driver failure will
not cause all subsequent carriers to silently move down by one.  In the event of
an error, the null carrier table is used for the current carrier number instead
of the requested table.

<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="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>

<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. 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(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 by calling <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 - 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(int carrier, int slot);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<tt>int carrier, int 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", "IPAH" or "VITA4" 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>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 - 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 - 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 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>

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

<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 - 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 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(int carrier, int slot);</pre>

<h4>
Parameters</h4>

<dl>
<dt>
<tt>int carrier, int 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 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>


<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 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>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 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>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 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="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 - 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="XVME9660"></a>Xycom XVME-9660/9670</h3>

<p>

These boards are four-slot, 6U VME carriers which are also sold by Acromag asthe AVME-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. A single bank of jumpers
provide the only hardware configuration, setting the base address of the board
in VME A16 space; module memory locations in VME A24 space 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 command <tt>ipacAddXy9660</tt> that registers an XVME-9660 board with
drvIpac. It 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);</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>ipacAddXy9660("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>

<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>
    int 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 and VIPC610
boards are totally dumb, and thus provide 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>