4 INSTALLATION GUIDE

The installation of the driver is done at start-up by script files and shall not be changed at run-time. It is composed by the installation of the driver code, common to all devices using the same board type, the installation of the devices corresponding to each driver, and the connection of interrupts, to vector numbers and interrupt service routines.

4.1 Installation Prerequisites

The following hardware and software prerequisites must be fulfilled for a successful installation of the driver.

4.1.1 Hardware Requirements

· Motorola 167 CPU, any version

· Controller board MAC4-INC Version 4.1
(In the script file listed in section 4.4 the jumpers are assumed to define the base address to 0xc10000 in the VMEbus A24 address space, and the interrupt level to 1)

· Ethernet network

· LCU console (terminal attached to the serial line of the VMEbus CPU)

4.1.2 Software Requirements

· VxWorks 5.2

· the lculog module version 1.9 or later must be loaded for logging purposes

· the lcudrv module version 1.16 or later for LCU common driver routines must be loaded

· the mcon module version 2.11 must be installed on a host machine

4.2 Building the Software

The mcon module is delivered as a UNIX tar file, either on disk or on tape. The tar file expands in a directory structure as defined in [8].

mcon/

|------include/ (include files)

|------src/ (mcon source files)

|------object/ (VxWorks objects)

|------doc/ (documentation)

|------test/ (mcon test sources and includes)

|------bin/ (boot scripts)

|------man/ (mcon manual pages)

If it is required to build or rebuild the software the Makefile provided shall be used. To use the Makefile a number of environment variables must be defined. An example to set up the environment for VxWorks and the GNU-C-compiler can be found in [9].

Before using the make files the user should make sure that GNU make is defined before the make supplied by the vendor in the search path. This can be checked by issuing the UNIX command which make. As defined in [8] VLT software should be built using GNU make in order to avoid discrepancies between different vendors implementation of make. To build the software follow the procedures below:

1. Move to mcon root directory (cd ./mcon)

2. Type make clean. This will remove everything which can be made, thus enforcing recompilation of the entire code.

3. Type make all man. This will compile and link everything. The result, the VxWorks object-module mcon and the installation script will be stored in directory mcon/bin.

4. Type make install. This will move the executables and include files required by external modules to their target directories.

4.3 Installation Procedure

This section describes the steps to install the MAC4 driver and the corresponding devices on the target LCU. A script file mconInstall is prepared to perform these steps. The utility vltMan can be used to access man-page informations for the mcon-functions.

1. Load the mcon driver code to the target system.

2. The driver is installed by invoking the function mconDrv() with the parameters:

· the maximum number of supported MAC4 devices

· the maximum number of open channels

· the access timeout in ticks

3. A device is installed by invoking the function mconDevCreate(), using as input parameters:

· the device name, e.g. "/mcon<i>", where <i> is the device unit number, starting with 0 and incrementing by one for each additional device.

· the base address of the board in the VMEbus standard A24 address space (e.g. 0xc10000)

· the number of the board channel used for the device (currently from 1 to 4)

· the backplane address of the board which will be used for location verification purposes.

· the vector number of the interrupt of the output buffer availability (e.g. 0xa0)

· the vector number of the interrupt of the 'drive fault' (e.g. 0xa1)

· the vector number of the interrupt of the 'motion end' (e.g. 0xa2)

· the vector number of the interrupt of the 'emergency stop' (e.g. 0xa3)

· the number of the interrupt-level (1 to 7)

· the version code which will be used for verification purposes (e.g. 0x00440308)

Applications using interrupts shall supply their own ISRs. All interrupts will be executed under the context of the task mconInt.

Warning: A unique vector number shall be given for each event and for each device, except for "emergency stop" (see section 3.5 on page 55).

4. Spawn the Maccon controller interrupt task. This task is currently defined to have a priority of 200 and a stack of 2000 bytes.

5. Enable VxWorks level 1 (as defined above) interrupt.

An installation script file mconInstall is prepared in the directory mcon/bin, which performs the above described installation procedure with default parameters. Only 4 devices corresponding to one MAC4 controller board will be installed. If more devices are needed the installation script has to be modified accordingly.

It is recommended to use this script only to install the MAC4 driver. A listing of the installation script is provided in the following section. To install the MAC4 driver do the following from the VxWorks shell of the target system:

· putenv "VWROOT=<drvRoot>") to set the environment variable VWROOT; <drvRoot> is the root directory into which the module mcon is installed

· invoke the installation script <drvRoot>/bin/mconInstall

4.4 Installation Script Example

The following installation script shall be called at system start-up time either included in a system start-up file or called from there.

#************************************************************************
# NAME
# mconInstall - install the MACCON driver and devices on target LCU
#
# SYNOPSIS
# mconInstall
#
# DESCRIPTION
# This script is used to load the Maccon driver module object from the host
# to the LCU target system and to configure the driver. This script must
# run on the LCU target system under the VxWorks shell.
#
# FILES
# 'mcon' must exist on the host system with group read access
#
# ENVIRONMENT
# The environment variable VWROOT must be set to LCU integration directory
# using the VxWorks function putenv("VWROOT=..........").
#
# RETURN VALUES
# none
#
# CAUTIONS
# This script must not be invoked more than once, at LCU system start-up
#
# EXAMPLES
# % < mconInstall
#
# SEE ALSO
# mconDrv(3), mconDevCreate(3),
# MACCON Driver User Manual
#
#------------------------------------------------------------------------
#

# load driver object

cd getenv("VWROOT")
cd "bin"
ld < mcon

# install and configure the MCON driver
mconDrv(4,10,100)

# install and configure the MCON devices

mconDevCreate("/mcon0",0xc10000,1,0,0xa0,0xa4,0xa8,0xac,1,0x00440308)
mconDevCreate("/mcon1",0xc10000,2,0,0xa1,0xa5,0xa9,0,1,0x00440308)
mconDevCreate("/mcon2",0xc10000,3,0,0xa2,0xa6,0xaa,0,1,0x00440308)
mconDevCreate("/mcon3",0xc10000,4,0,0xa3,0xa7,0xab,0,1,0x00440308)

# install MCON interrupt handle task

taskSpawn ("tintMCON ", 200, 0x18, 2000, mconInt)

# change to root directory
cd ".."

4.5 Installation Verification

Functions performed during installation phase always log OK or ERROR messages to the console.

The tools described in a previous section can be used to test that the driver and the device(s) have been installed correctly. From the VxWorks shell issue the following commands:

· mconVersion
Prints the versions of the driver and the controller on the screen.

· mconDevShow
This should dump the base-addresses of all installed mcon devices on the console.

· mconStAll
This prints status information about all installed mcon devices.

If any of the procedures described above do not work as expected it may be useful to switch on the LCU debugging and tracing facility. This can be achieved by issuing the following commands to the VxWorks shell: LCU_debug and LCU_trace. Both functions should return the value 1.

Then execute the test procedures again and examine the debugging and tracing messages.

To switch the debugging and tracing facilities off just issue the corresponding commands again and this time they should return the value 0.