CHANGE RECORD

Issue	Date	Affected Paragraphs(s)	Reason/Initiation/Remarks
1.0	15/05/2005	All	First preparation

The information contained in this manual is intended to be used in the ESO

VLT project by ESO and authorized external contractors only.

While every precaution has been taken in the development of the software

and in the preparation of this documentation, ESO assumes no responsibility

for errors or omissions, or for damage resulting from the use of the software

or of the information contained herein.

TABLE OF CONTENTS

1. INtRoduction........................................................................................................................................................................... 7

1.1 Scope...................................................................................................................................................................................... 7

1.2 Applicable Documents......................................................................................................................................................... 8

1.3 Reference Documents.......................................................................................................................................................... 8

1.4 List of Abbreviations/Acronyms....................................................................................................................................... 9

1.5 Stylistic Conventions........................................................................................................................................................... 9

1.6 Naming Conventions............................................................................................................................................................ 9

2. User’s Guide............................................................................................................................................................................. 10

2.1 General about Drivers......................................................................................................................................................... 10

2.2 Overview.............................................................................................................................................................................. 10

2.3 A201S Carrier Board........................................................................................................................................................... 11

2.3.1 Carrier Board Address Map..................................................................................................................................... 11

2.4 User Interface to the Driver............................................................................................................................................... 12

2.5 Interrupts.............................................................................................................................................................................. 13

2.5.1 M27/28 – Digital Output Module............................................................................................................................ 13

2.5.2 M31 – Digital Input Module..................................................................................................................................... 13

2.5.3 M36/M37 – Analog Input/Output Module............................................................................................................ 14

2.5.4 M58 – TTL I/O Board................................................................................................................................................ 14

2.6 The M58 Module................................................................................................................................................................ 15

2.6.1 Data Modes................................................................................................................................................................ 15

2.6.2 Port Termination......................................................................................................................................................... 15

3. Reference................................................................................................................................................................................. 16

3.1 Introduction......................................................................................................................................................................... 16

3.2 Functions............................................................................................................................................................................. 16

3.2.1 open()........................................................................................................................................................................... 16

3.2.2 close().......................................................................................................................................................................... 18

3.2.3 ioctl()............................................................................................................................................................................ 19

3.2.4 mendrvDrv()................................................................................................................................................................ 21

3.2.5 mendrvDevCreate().................................................................................................................................................... 22

3.3 IOCTL Commands............................................................................................................................................................... 23

3.3.1 Common Commands.................................................................................................................................................. 23

3.3.2 Digital I/O Module Commands................................................................................................................................ 25

3.3.3 Analog Module I/O Commands............................................................................................................................... 29

3.4 Logging................................................................................................................................................................................ 32

3.5 Include Files......................................................................................................................................................................... 32

3.6 Tools..................................................................................................................................................................................... 33

4. Installation......................................................................................................................................................................... 34

4.1 Installation Prerequisites................................................................................................................................................... 34

4.1.1 Hardware Requirements............................................................................................................................................ 34

4.1.2 Software Requirements............................................................................................................................................. 34

4.2 Building the Software......................................................................................................................................................... 34

4.3 The Installation Procedure................................................................................................................................................ 35

4.3.1 Installation Script Example........................................................................................................................................ 36

4.3.2 Device Creation.......................................................................................................................................................... 37

4.4 Installation Verification...................................................................................................................................................... 39

5. Error Messages and Recovery.................................................................................................................................... 40

5.1 Common Driver Errors........................................................................................................................................................ 40

5.2 MENDRV Specific Errors................................................................................................................................................... 41

LIST OF FIGURES

Figure 1: A201S Jumper Configuration. 11

Figure 2: Possible Addresses for A201 Modules. 11

1. INtRoduction

This document is the User Manual of the MEN Analog and Digital I/O M-Modules Driver Software module (mendrv).

It is intended to provide all the necessary information to use the mendrv driver from the LCU Common Software or higher level applications.

The manual assumes that the reader has a good knowledge of UNIX, C-language, the VxWorks operating system and is familiar with the VxWorks development environment.

In addition to the Introduction section, this manual contains four major sections:

User’s Guide: describes the tasks, that can be done by the driver, including examples.
Reference: lists and describes all functions available.
Installation Guide: explains how to install the driver and make it ready for use.
Error Messages and Recovery: lists and describes driver specific error messages.

At the end, the Error Messages and Recovery section provides a complete list of errors and diagnostic messages and possible error recovery actions.

1.1 Scope

This document provides the User Manual of the software module mendrv in its version 1.0.

The mendrv driver is developed for the following MEN Analog and Digital I/O Modules based on the MEN VME Carrier board A201S

M28 (16 ground referenced opto-isolated inputs),
M31 (16 ground referenced opto-isolated buffered 500mA outputs),
M58 (32 TTL I/O signals not insulated),
M36 (8/16 channels 16bits analog inputs) and
M37 (4 channels 16bits analog outputs).

This implementation includes the following C library:

mendrv – library of routines to access the mendrv module

The following hardware and software environment is required to run the driver software described:

a standard 6U VMEbus chassis with bus backplane and power supply
at least one PPC MV2604/MV2700 CPU board
at least one MEN VME Carrier Board A201S
at least one MEN I/O Board of type M27/28, M31, M36, M37, M58
VxWorks 5.4 operating system or higher
lcudrv for common driver functions, version 1.33 or higher
lculog for internal logging, version 1.12 or higher

The following documents, of the exact issue shown, form a part of this document to the extent specified herein. In the event of conflict between the documents referenced herein and the contents of this document, the contents of this document shall be considered as a superseding requirement.

[1] VLT-SPE-ESO-10000-0011, 2.0, 30/09/92 --- VLT Software Requirements Specification

[2] VLT-SPE-ESO-10000-0010, 1.1 16/10/91 --- VLT Software Concept Specification

[3] VLT-PRO-ESO-10000-0228 1.0 VLT Software Programming Standards

[4] VLT-MAN-ESO-17210-0375 2.2 VLT Software - CCS/LCU Driver Development Guide and User Manual

[5] VLT-MAN-ESO-17200-0908 1.4 VLT Software - Tools for Automated Testing - User Manual

[6] VLT-MAN-ESO-17200-0780 2.0 VLT Software - Configuration Management Module – User Manual

1.3 Reference Documents

The following documents are referenced in this document.

[7] VLT-MAN-ESO-17210-0364 2.0 VLT Software - Digital I/O driver - User Manual

[8] VLT-MAN-ESO-17210-0462 1.4 VLT Software - Analog I/O driver - User Manual

[9] VLT-MAN-ESO-17210-2806 1.0 VLT Software - CAN Open Analog/Digital I/O driver - User manual

[10] VLT-TRE-ESO-10000-3423 1.0 MEN A201S Carrier Board and MEN Digital I/O M-Modules - Test Report

[11] VLT-TRE-ESO-10000-3424 1.0 MEN Analog I/O M-modules - Test Report

[12] VxWorks 5.4 Documentation Kit

[13] MEN GmbH Documentation http://www.men.de/

[14] 20A201S00 E4 MEN A201S User Manual

[15] 20M028-00 E2 MEN M28 User Manual

[16] 20M031-00 E4 MEN M31 User Manual

[17] 20M058-00 E3 MEN M58 User Manual

[18] 20M036-00 E4 MEN M36 User Manual

[19] 20M037-00 E2 MEN M37 User Manual

[20] VLT-SPE-ESO-17210-0375 1.0 CCS-LCU Driver Development Guide and User Manual

1.4 List of Abbreviations/Acronyms

The following abbreviations and acronyms are used in this document:

AIO Analog I/O Interface Module

BSP Board Support Package

CCS VLT Central Common Software

CDT Command Descriptor Table

CMM Configuration Management Module

CPU Central Processing Unit

DCT Driver Channel Table

EOC End of analog-to-digital conversion

HW / SW Hardware / Software

ISR Interrupt Service Routine

LCC LCU Common Software

LCU Local Control Unit

MEN Mikro Elektronik Nürnberg GmbH

N/A Not Applicable

OS Operating System

(D)RAM (Dual) Random Access Memory

RIX Review Item Discrepancy/Comment/Question

ROAK Release On Acknowledge (Interrupt)

TBC/D To Be Confirmed / Defined

VME Versa Module Eurocard

VLT Very Large Telescope

1.5 Stylistic Conventions

The following styles are used:

bold

in the text, for commands, filenames, pre/suffixes as they have to be typed.

italic

in the text, for parts that have to be substituted with the real content before typing.

teletype

for examples.

<name>

in the examples, for parts that have to be substituted with the real content before typing.

bold and italic are also used to highlight words.

1.6 Naming Conventions

This implementation follows the naming conventions as outlined in the VLT Programming standards [3].

2. User’s Guide

This part of the document provides a functional description of the mendrv driver module.

2.1 General about Drivers

In general, a software which controls a specific hardware is called a driver and the hardware to be controlled is called device. In case of the VLT LCUs the devices are VMEbus printed circuit boards. The driver runs on the CPU-board of the VMEbus system and is able to control several devices of the same type. To the user's side the driver provides a set of functions which can be invoked through the VxWorks I/O system and allow access to a device from higher level software applications. Thereby this access provides a more logical view of the device as needed for programming purposes and hides the hardware related details.

2.2 Overview

The program controlling hardware is usually called driver, and the specific hardware to control is called a device. The driver can control several devices simultaneously, where each device consists of the same type of hardware, using the same code but with different sets of data for each device. The set of data defining the device and containing the status of the device is called device descriptor table. The driver concept of VxWorks is described in [12].

The software interface to the supported MEN analog and digital I/O boards consists of a set of registers to set output signals, to read input signals, to configure interrupts, to get the interrupt status and to get the status of the board. The analog I/O board can also do auto calibration of the input signals.

Currently the driver supports the following MEN analog and digital I/O boards:

M28 - 16 ground referenced opto-isolated inputs
M31 - 16 ground referenced opto-isolated buffered 500mA outputs
M58 - 32 TTL I/O signals not insulated
M36 - 8/16 channels 16bits analog inputs
M37 - 4 channels 16bits analog outputs

The driver supplies commands to manage the interrupt sources. The user routine shall not do any direct accesses to the MEN I/O board hardware, but shall use the commands to the driver.

The driver supports several MEN analog and digital I/O modules on different carrier boards in the same system, where each module represents one device. These devices share the same driver code and only have different sets of data (device descriptors).

Currently the driver only supports the carrier board MEN A201S.

2.3 A201S Carrier Board

Currently the driver only supports the carrier board MEN A201S, which can handle up to four different M-Modules at the same time. In order to work properly the right address configuration has to be configured via jumpers which are located at the rear part of the board.

Both A16 and A24 address mode are supported by the driver.

Figure 1: A201S Jumper Configuration

2.3.1 Carrier Board Address Map

The table below gives a detailed repartition of the addresses among the M-Modules devices depending on the A201 carrier board base address

Figure 2: Possible Addresses for A201 Modules

Note that the carrier boards must be located at the addresses shown in the table following the convention that

no gap between two A201S is allowed.

The population of a single carrier board regarding M-modules is free, especially empty slots are allowed. The file mendrv.boot which is part of the module includes all the combinations for A16 and A24 addressing for up to 16 devices for each of the address spaces (see section 4.3.2).

2.4 User Interface to the Driver

The mendrv driver provides the standard VxWorks I/O system interface to the user, i.e. the open, close and ioctl system calls.

To get access to the device a user has to open a channel to it by calling the open routine with a file name, specifying the device and an open mode. The filename of a men device is made up of two parts:

• the driver name men and

• the device unit 0, 1, 2 ...

so, for instance /men0 would specify the first men device in a LCU.

The open mode specifies the access rights to the device which are controlled by the driver. The open mode can be:

· Read-Only access: on a channel opened in this mode only read commands can be issued.

· Exclusive read/write access: write access is granted only to the user that performed the open with this option. Requesting Exclusive access to a device already opened in Exclusive or Shared access mode gives back an error.

· Shared read/write access: write access is granted to the user that performed the open and to any other task that later on will request a similar open. Requesting Shared access to a device already opened in Exclusive access mode gives back an error.

· Test read/write access: write access is granted to the user that performed the open with this option without limitation to the present opening status. Requesting Test access to a device already opened in Test access mode gives back an error, i.e. Test access mode is only granted to one user. This mode shall only be used by test and maintenance software. The idea is that test and maintenance software can access the driver without interfering with other users of the driver.

The open call returns a file handle with which the channel is identified in any further driver calls.

An open channel to a device can be closed with the close system call.

All functions performed by the mendrv driver are activated with the ioctl call. The ioctl call has a parameter specifying the action requested by the driver. This parameter is called ioctl control command throughout this document.

The ioctl control commands are grouped into read and write commands. Read commands are used to read values or status from the board, while write commands are used to write values or perform some action.

In addition an ioctl control command has a further parameter which is an argument of the command. If the command needs multiple arguments then this parameter is the address of a data structure which contains these multiple arguments. All needed data structures are provided in the Module Interface File mendrvCommands.h.

The driver calls are mutually exclusive, that is the device accessed by a user is protected from access from any other authorized user until the executing driver call has terminated. This means that when an user is executing a driver call and another user tries to access the driver for the same device, then the second user task will be blocked until the driver call of the first one has terminated. The blocked task will be put on a queue. The tasks on the queue will be scheduled according to their priority. The driver uses the VxWorks mutex semaphore for this purpose to provide priority inheritance, see reference.

A task, blocked for access of a device will have a timeout. The timeout value is a general driver parameter and can be set/asked with the mendrvSet/GetTimeout command. After the timeout interval has expired without the task having got access to the device the call is rejected with an error code and the task is resumed.

2.5 Interrupts

Most of the MEN modules support interrupts indicating certain events/status on/of the board.

2.5.1 M27/28 – Digital Output Module

This module does not provide any interrupt.

2.5.2 M31 – Digital Input Module

If enabled, an interrupt is triggered as soon as the state of one of the inputs changes.

Interrupts can be enabled or disabled by the commands mendrvCMD_ENABLE_INTERRUPT and mendrvCMD_DISABLE_INTERRUPT for each signal individually. The interrupting state is also defined by the enable-command. Note that the value given here defines a logical state (active or inactive, corresponding to the current configuration), not a physical (high or low). However, if the signal configuration is changed afterwards, then the physical setting will be retained, not the logical.

If applications use the interrupt feature, they must provide an interrupt routine (User-ISR) by the command mendrvCMD_CONFIG_INTERRUPT. By default a dummy ISR - which only logs a warning - is used. A parameter which is passed to the User-ISR can also be specified. This routine shall be common to all interrupts and is executed in task mode (namely in the context of the driver provided interrupt task), not in interrupt mode. A bit-mask of all currently pending interrupts is passed as second parameter to the User-ISR, which has to examine this value in order to service all requests. Bit 0 corresponds to signal 0, Bit 15 to signal 15. A ‘1’ bit indicates that an interrupt is pending from the corresponding signal.

Note that the User-ISR has not to deal with clearing the interrupt request in the Digital I/O board.

An example of a User-ISR is and its installation:

static int mendrvFd;

static mendrvENABLE_INT argEna;

* User-ISR logs a message on every state change of signal 0

void mendrvUserIsr(int parameter, u_char pendingMask)

{

logMsg(“\n--- M31 Interrupt: par=%d, mask=0x%02x ---\n”,

parameter,pendingMask,0,0,0,0);

if (pendingMask & 1)

{

* Invert the polarity and re-enable:

* (Inversion is necessary to get each

* state change)

argEna.numSignal = 0;

argEna.polarity ^= 1;

(void)ioctl(mendrvFd, mendrvCMD_ENABLE_INTERRUPT,

(int)&argEna);

}

* Install the User-ISR

int foo(void)

{

int status;

mendrvCONFIG_INT argCfg;

mendrvFd = open(“/men0”, lcudrvOPEN_SHARED, (int)&status);

if (mendrvFd < 0) return(status);

* Connect the User-ISR

argCfg.routine = mendrvUserIsr;

argCfg.parameter = 0;

status = ioctl(mendrvFd, mendrvCMD_CONFIG_INTERRUPT, (int)&argCfg);

if (status != lcudrvOK) return(status);

* Enable signal 0 to interrupt when it is in active state

argEna.numSignal = 0;

argEna.polarity = 1;

status = ioctl(mendrvFd, mendrvCMD_ENABLE_INTERRUPT, (int)&argEna);

if (status != lcudrvOK) return(status);

return(status);

}

The command mendrvCMD_READ_INTERRUPT_STATUS returns the status of interrupt handling.

The command mendrvCMD_CLEAR_INTERRUPT tries to clear a pending interrupt request for a signal.

2.5.3 M36/M37 – Analog Input/Output Module

Both modules support interrupts

The M36 - Analog Input Module triggers an interrupt every time the internal address pointer of the current data element points to data element 0 (when all enabled channels are sampled)
The M37 - Analog Output Module triggers an interrupt at the end of each conversion cycles.

Note: On both modules the conversion runs cyclically in an endless loop; so the interrupt is triggered with the rate of the conversion cycle.

Currently the driver does not support any interrupt handling for these boards. During initialization of such a device the driver disables all interrupts on level of the carrier board as well as on the level of the module.

2.5.4 M58 – TTL I/O Board

If enabled this board triggers an interrupt when the defined edge of the trigger signal[1] occurs. The edge can be defined using the command mendrvCMD_SET_TTL_LATCH; the default is trigger on rising edge.

The interrupt can be enabled or disabled by the commands mendrvCMD_ENABLE_INTERRUPT and mendrvCMD_DISABLE_INTERRUPT. Since the interrupt only refers to the trigger signal, the parameters to be passed with these commands are insignificant and so ignored by the driver.

Like for the M31 module applications using the interrupt feature have to provide an interrupt routine (User-ISR) using the command mendrvCMD_CONFIG_INTERRUPT. By default a dummy ISR - which only logs a warning - is used. A parameter which is passed to the User-ISR can also be specified. This routine is executed in task mode (namely in the context of the driver provided interrupt task), not in interrupt mode. When invoked a mask of 32 bits is passed as second parameter; this mask returns the current status of all 32 I/Os of the module. Bit 0 corresponds to signal 0 of port A and bit 31 signal 7 of port D.

2.6 The M58 Module

The M58 module provides some additional features, which are partly supported by the mendrv module as well.

2.6.1 Data Modes

The M58 module supports several data storage modes defining the time when input data is stored before it can be read. The mode can be setup using the command mendrvCMD_SET_TTL_LATCH . Currently the mendrv module supports the following modes

· mendrvTTL_LATCH_MODE_NORMAL – each port is stored directly when read

· mendrvTTL_LATCH_MODE_TRIGGER – ports A, B and C are stored when read, port D is stored on the trigger signal.

· mendrvTTL_LATCH_MODE_DATABUS – all ports are stored on the trigger signal

2.6.2 Port Termination

If binary data is to be transmitted over longer distances a line termination resistor is necessary. This termination can be enabled or disabled on port level. The corresponding command provided by the mendrv module is mendrvCMD_SET TTL_TERMINATOR.

3. Reference

3.1 Introduction

This chapter provides a detailed description of the MEN Analog and Digital I/O Driver module interface to the user, namely functions, commands, include files and tools.

The functions are described in UNIX man-page format and are organized in a functional order. Below is an index of the routines in the same order.

CAUTIONS

· A zero value should never be returned.

· A cast to (int) for the third parameter is necessary because the declaration in VxWorks overrides the one shown here.

· Device names shall not be longer than 15 characters. They are defined by use of the function mendrvDevCreate() at startup.

· The number of opened channels for all devices of the driver is limited to the value defined at installation-time.

· The returned file descriptor can be shared by several applications.

· Applications can have the same device opened several times, using different file descriptors. Furthermore, open modes can be mixed according to the rules previously described.

· As only one task can open a device for Exclusive mode at any one time, and the number of channels is limited, applications should issue a close call if no more action on the device has to be performed.

VxWorks

· The VxWorks include file configAll.h contains two literals used by iosInit function: NUM_DRIVERS which defines the maximum number of drivers allowed, and NUM_FILES, the maximum number of simultaneously open files. They are respectively defined as 20 and 50.

· The VxWorks command iosDrvShow() shows all drivers of the system and their basic I/O function entry-points. The command iosFdShow() shows all currently used file descriptors, and iosDevShow() (or devs) all installed devices.

3.2.2 close()

NAME

close - close a channel to an MEN Analog and Digital I/O device

SYNOPSIS

#include "mendrv.h"

int close (int fileDescriptor)

DESCRIPTION

This operation closes a channel to an opened device and frees the file descriptor. fileDescriptor must correspond to

one of those obtained previously be an open call.

RETURN VALUES

lcudrvOK if successfully done.
Other error codes returned by the driver are described in chapter .

EXAMPLES

int fd, status;

int closeError;

fd = open ("/men0", lcudrvOPEN_TEST, (int)&status);

......

closeError = close (fd);

if (closeError != lcudrvOK)

{

/* error processing */

......

}

else

{

/* normal processing */

......

}

CAUTIONS

· This function is not queued by the driver, it always returns on of the above two status codes immediately.

3.2.3 ioctl()

NAME

ioctl - send a control command to a men device

SYNOPSIS

#include "mendrv.h"

int ioctl (int fileDescriptor, int command, void *argument)

DESCRIPTION

This function commands the driver to perform the specified operation on the device. The commands are divided

into read and write commands. Read commands are allowed in each open mode while write commands will be

rejected if the channel was not previously opened in Shared, Exclusive or Test mode.

fileDescriptor must correspond to one of those obtained previously by an open operation
command is a number, identifying the operation to be performed by the driver. Literals of all commands are provided in mendrvCommands.h. The following commands are supported:

Common Commands

mendrvCMD_RESET - reset device
mendrvCMD_FREE_DEVICE - free device
mendrvCMD_CONFIG_INTERRUPT - configure interrupt
mendrvCMD_ENABLE_INTERRUPT - enable interrupt
mendrvCMD_DISABLE_INTERRUPT - disable interrupt
mendrvCMD_CLEAR_INTERRUPT - clear interrupt
mendrvCMD_READ_INTERRUPT_STATUS - read interrupt status
mendrvCMD_SET_TIMEOUT - set time-out
mendrvCMD_GET_TIMEOUT - get time-out
mendrvCMD_GET_BOARD_ID - read board ID

Commands for Digital I/O Modules

mendrvCMD_BLOCK_SEMAPHORE - block semaphore
mendrvCMD_READ_CONFIG_BITS - read I/O configuration
mendrvCMD_WRITE_CONFIG_BITS - write I/O configuration
mendrvCMD_READ_BITS - read bits
mendrvCMD_WRITE_BITS - write bits
mendrvCMD_WRITE_SET_BIT - set bits
mendrvCMD_CLEAR_BIT - clear bits
mendrvCMD_CHANGE_BIT - change bits
mendrvCMD_CHECK_PULSE_BIT - check pulse bit
mendrvCMD_WRITE_PULSE_BIT - write pulse bit
mendrvCMD_RESET_PULSE_BIT - reset pulse bit
mendrvCMD_NUM_DIGITAL_INPUTS - return number of digital inputs
mendrvCMD_NUM_DIGITAL_OUTPUTS - return number of digital outputs
mendrvCMD_SET_TTL_TERMINATOR - enable/disable termination resistors
mendrvCMD_SET_TTL_LATCH - configure storage mode

Command for Analog I/O Modules

mendrvCMD_GET_INPUT_CONFIG - get analog input configuration
mendrvCMD_GET_OUTPUT_CONFIG - get analog output configuration
mendrvCMD_SET_INPUT_CONFIG - set analog input configuration
mendrvCMD_SET_OUTPUT_CONFIG - set analog output configuration
mendrvCMD_ENABLE_EOC_INTERRUPT - enable EOC interrupt
mendrvCMD_DISABLE_EOC_INTERRUPT - disable EOC interrupt
mendrvCMD_AUTOCALIBRATION - perform autocalibration
mendrvCMD_GET_GAIN - get gain
mendrvCMD_SET_GAIN - set gain
mendrvCMD_READ_VALUE - read analog value
mendrvCMD_WRITE_VALUE - write analog value
mendrvCMD_READ_BIN_VALUE - read binary value
mendrvCMD_WRITE_BIN_VALUE - write binary value
mendrvCMD_WAIT - wait (for test purposes)
mendrvCMD_NUM_ANALOG_INPUTS - return number of analog inputs
mendrvCMD_NUM_ANALOG_OUTPUTS - return number of analog outputs

argument is the address of the command argument, or NULL if no argument is used. For commands, needing multiple arguments it is the address of a data structure which contains those. All argument data structures are defined in the include file mendrvCommands.h

RETURN VALUES

lcudrvOK if successfully done.
lcudrvERROR_ACCESS_CONFLICT if the write command can not be executed by use of a file descriptor previously obtained with a read-only open mode.
lcudrvERROR_INVALID_ARGUMENT if command code is invalid.
lcudrvERROR_TIMEOUT if access protection timed out.
Other command specific values returned by the driver are described in chapter .

EXAMPLES

int fd, status;

int arg;

int ioctlError;

fd = open ("/men0", lcudrvOPEN_TEST, (int)&status);

......

ioctlError = ioctl (fd, mendrvCMD_SET_TIMEOUT, (int)&arg);;

if (ioctlError != lcudrvOK)

{

/* error processing */

......

}

else

{

/* normal processing */

......

}

CAUTIONS

· This function is protected by a semaphore, and commands are queued by application priorities rather than by First-in First-out.

· A watchdog timer is implemented to ensure the permissible maximum execution delay of a command. This delay, expressed in ticks (currently there are 100 ticks in 1 second) and can be set/got at run-time by two additional commands: mendrvCMD_SET/GET_TIMEOUT.

· The type of the third parameter is declared as int in VxWorks. Therefore a cast is necessary.

3.2.4 mendrvDrv()

NAME

mendrvDrv – install the MEN Analog and Digital I/O device driver

SYNOPSIS

#include "mendrv.h"

int mendrvDrv (int device, int maxChannels, int timeout)

DESCRIPTION

This routine installs the MEN device driver. Its is called on start-up and initializes the channel and device management.

The routine must be called any I/O request to the driver and before installing a MEN device.

RETURN VALUES

lcudrvOK if successfully done.
lcudrvERROR_DRIVER_EXISTS if driver is already installed
lcudrvERROR_INVALID_ARGUMENT if invalid channel count
lcudrvERROR_NO_MEMORY if no memory for internal data
lcudrvERROR_NO_SEMAPHORE if mutex-semaphore cannot be created

CAUTIONS

· This routine must only be called once and before installing a MEN device.

3.2.5 mendrvDevCreate()

NAME

mendrvDevCreate – add a new device to the MEN Analog and Digital I/O device driver

SYNOPSIS

#include "mendrv.h"

int mendrvDevCreate (char *name, void *baseAddr, int intrNumber, int intrLevel, int type)

DESCRIPTION

This function is called at start-up once for each device to be installed. It adds a device to the driver, making it

available for subsequent open operations.

devName - device name (must be "/menX" X>=0, e.g. "/men0")
busAddr - VMEbus base address of the board in the A16 (0x1000 – 0x2E00)

or A24 (0x11000 – 12E000) address space

intrNumber - interrupt-vector-number of the device interrupt
intrLevel - level of the device interrupt
type - additional parameter only needed for M36 devices

if TRUE device is operated in single-ended mode

if FALSE device is operated in differential mode

RETURN VALUES

lcudrvOK if successfully done.
lcudrvERROR_INVALID_ARGUMENT if invalid channel count
lcudrvERROR_NO_MEMORY if no memory for internal data
lcudrvERROR_NO_SEMAPHORE if mutex-semaphore cannot be created
lcudrvERROR_TIMEOUT if semaphore-timeout
lcudrvERROR_DEVICE_EXISTS if device is already installed

CAUTIONS

· The MENDRV driver must be installed before using this routine.

3.3 IOCTL Commands

This section describes all control commands which can be invoked by use of the VxWorks ioctl function. The parameter command specifies which operation has to be performed by the driver while the parameter argument passes the address of an argument to the command handler. In cases where multiple arguments are needed the address of a structure which contains those is passed.

All command literals and argument data structures are defined in the include file mendrvCommands.h.

The supported commands can be divided into three groups: Common, Digital I/O and Analog I/O Commands.

This section describes all control commands supported by the driver, namely their purpose, arguments and return codes.

3.3.1 Common Commands

mendrvCMD_RESET – reset device

Resets the device and puts all I/Os into their standard state. Digital inputs/outputs are set to active low, analog outputs are set to 0 and the gain of all analog input signals is set to 1.

Arguments: none

Return Values:

o lcudrvOK – successful completion

o mendrvERROR_CONFIGURATION – low level board access routine returns an error

mendrvCMD_FREE_DEVICE – free the device

This command frees the access to the driver when it is blocked by a task which has opened it in exclusive mode and terminated without closing or hang-up, etc. In this case it is not possible to give any write command to the driver from other tasks. The 'free device' command cleans this situation by closing the exclusive channel. The intention is that this command should be used manually by an operator only and not from other tasks which just want to give write commands.

Argument: none

Return Values:

o lcudrvOK - successful completion

o mendrvERROR_NO_EXCLUSIVE - no exclusive channel was opened

mendrvCMD_CONFIG_INTERRUPT – configure interrupt (M31/M58 modules only, see section 2.5)

This command defines a user supplied routine to be called on interrupts.

Argument: address of an mendrvCONFIG_INT data structure with the fields

.routine the address of the user routine

.parameter the parameter to be sent to the routine on an interrupt

Return Values:

o lcudrvOK - successful completion

o lcudrvERROR_INVALID_ARGUMENT - command valid but argument is out of range

o mendrvERROR _CONFIGURATION – command is not applicable for MEN module

mendrvCMD_ENABLE_INTERRUPT – enable interrupt (M31/M58 modules only, see section 2.5)

In case of the M31 module this command enables an interrupt for a signal, before that it tries to clear any pending requests. If the signal is already in the interrupting state, then an interrupt will occur immediately. Note that it is disabled automatically when serviced by the internal ISR.

Argument: address of an mendrvENABLE_INT data structure with the fields

.numSignal the signal number (range depends on MEN module)

.polarity the polarity of the signal causing an interrupt; a 0 indicates interrupt on signal inactive state, a 1 on signal active state, dependent on the current signal configuration.

In case of the M58 module this command enables the interrupt for the trigger signal according to the configuration done with the command mendrvCMD_SET_TTL_LATCH. The input parameter for the command mendrvCMD_ENABLE_INTERRUPT are ignored.

Return Values:

o lcudrvOK - successful completion

o lcudrvERROR_INVALID_ARGUMENT - command valid but argument is out of range

o mendrvERROR _CONFIGURATION – command is not applicable for MEN module

mendrvCMD_DISABLE_INTERRUPT – disable interrupt (M31/M58 modules only, see section 2.5)

In case of the M31 module this command disables the interrupt for a signal. Any pending requests are not cleared.

Argument: address of an integer value, containing the signal number (depends on the MEN module)

In case of the M58 module the interrupt for the trigger signal is disabled. The input parameter is ignored.

Return Values:

o lcudrvOK - successful completion

o lcudrvERROR_INVALID_ARGUMENT - command valid but argument is out of range

o mendrvERROR _CONFIGURATION – command is not applicable for MEN module

mendrvCMD_CLEAR_INTERRUPT – clear interrupt (M31/M58 modules only, see section 2.5)

This command clears the interrupt of a MEN module by calling the internal driver ISR.

Argument: address of an integer value, containing the signal number (depends on the MEN module); this parameter has no meaning and is ignored by the driver.

Return Values:

o lcudrvOK - successful completion

o lcudrvERROR_INVALID_ARGUMENT - command valid but argument is out of range

o mendrvERROR _CONFIGURATION – command is not applicable for MEN module

mendrvCMD_READ_INTERRUPT_STATUS – read interrupt status (M31/M58 modules only, see section 2.5)

Returns the interrupt status of the corresponding MEN module

Argument: address of an integer value, receiving the interrupt status value; the following values are possible

0 – interrupts are disabled
1 – interrupts are enabled

Return Values:

o lcudrvOK - successful completion

o mendrvERROR _CONFIGURATION – command is not applicable for MEN module

mendrvCMD_SET_TIMEOUT – set driver time-out

This command sets the timeout of the driver. The value must be specified in system clock ticks. The driver timeout specifies how long a control command is waiting for access to the device before it is timed out.

Argument: address of an integer, containing the timeout value in system clock ticks.

Return Values:

o lcudrvOK - successful completion

o lcudrvERROR_INVALID_ARGUMENT - timeout value out of range

mendrvCMD_GET_TIMEOUT – return driver time-out

Returns the timeout of the driver in ticks, i.e. the maximum time the user's task has to wait for device access before it will be timeout.

Argument:address of an integer, receiving the timeout value

Return Values:

o lcudrvOK - successful completion

mendrvCMD_GET_BOARD_ID – return ID of MEN module

Returns a pointer to the ID string of the MEN module.

Argument: address of an integer, receiving the pointer to the board ID string

Return Values:

o lcudrvOK - successful completion

3.3.2 Digital I/O Module Commands

mendrvCMD_BLOCK_SEMAPHORE – block semaphore

Takes the device specific semaphore and locks it for the time specified by the argument. During this time no write and configuration requests for that device are possible.

Argument: address of an integer, containing the time-out value in system clock ticks.

Return Values:

lcudrvOK - successful completion

o mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_READ_CONFIG_BITS – read multiple configuration bits

This command returns the configuration of the specified signal(s). One signal or several consecutive signals.

Argument: address of an mendrvCONFIG data structure with the fields

.firstSignal (in) the number of the first signal

.numSignal (in) the number of signals; the sum of the number of the first signal and number of signals must be less than or equal to the number of available I/Os (see MEN User Manuals)

.inputOutput (out) the input/output configuration, where a one indicates an output and a zero an input. This parameter is returned by the driver.

.polarity (out) the active signal level, where a one indicates signal active high and a zero signal active low; the value is right shifted, i.e. bit 0 contains the state of the first signal, bit 1 the second etc. This parameter is returned by the driver.

Return Values:

lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT – invalid number of signal(s)
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_WRITE_CONFIG_BITS – configure bits

This command configures the signal(s) as input or output and sets the signal to inactive state.

Argument: address of an mendrvCONFIG data structure with the fields

.firstSignal the number of the first signal

.numSignal the number of signals; the sum of the number of the first signal and number of signals must be less than or equal to the number of available I/Os (see MEN User Manuals)

.inputOutput the input/output configuration, where a one indicates an output and a zero an input.

.polarity the active signal level, where a one indicates signal active high and a zero signal active low. The value is used for all specified signals.

Return Values:

lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT – invalid number of signal(s)
mendrvERROR_PULSEBIT_IN_PROGRESS - change a signal during pulse time
mendrvERROR_CONFIGURATION – command or configuration is not applicable for MEN module

Notes:

The inputOuput configuration of the MEN Modules M27 and M31 is not configurable; M27 is a digital output module and M31 a digital input module. The parameter .inputOutput must comply with the type of the module.
The inputs/outputs of the M58 module are organized in so-called ports of eight signals, which can only be configured on the level of a port. So it is not possible to configure each signal individually. The driver handles the configuration of a single signal in the following way

The configuration of the first signal of a port defines the configuration of the complete port
If this command is used for other signals than the first one of a port, the configuration passed is just verified with the one currently setup for the complete port.

mendrvCMD_READ_BITS – read multiple I/O signals

This command returns the states of the specified input signal(s). One signal or several consecutive signals.

Argument: address of an mendrvREAD_D data structure with the fields

.firstSignal (in) the number of the first signal

.numSignal (in) the number of signals; the sum of the number of the first signal and number of signals must be less than or equal to the number of available I/Os (see MEN User Manuals)

.returnValue (out) the signal status, where a one in the corresponding bit indicates that the signal is active; the value is right shifted, that is bit 0 contains the state of the first signal, bit 1 the second signal etc. This parameter is returned by the driver.

Return Values:

lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT – invalid number of signal(s)
mendrvERROR_PULSEBIT_IN_PROGRESS - change a signal during pulse time
mendrvERROR_CONFIGURATION – command is not applicable for MEN module or signal is not an input

mendrvCMD_WRITE_BITS – write multiple I/O signals

This command writes a value to the signal(s) specified. One signal or several consecutive signals.

Argument: address of an mendrvWRITE_D data structure with the fields

.firstSignal the number of the first signal

.numSignal the number of signals; the sum of the number of the first signal and number of signals must be less than or equal to the number of available I/Os (see MEN User Manuals)

.value the signal(s) states, where the range must correspond to the number of signals specified; bit 0 of the value shall contain the state of the first signal, bit 1 the second signal etc.

Return Values:

lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT – invalid number of signal(s)
mendrvERROR_PULSEBIT_IN_PROGRESS - change a signal during pulse time
mendrvERROR_CONFIGURATION – command is not applicable for MEN module or signal is not an output

mendrvCMD_WRITE_SET_BIT – set a signal

This command sets a signal to its active state.

Argument: address of an integer value, containing the number of signal to be set.

Return Values:

lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT – invalid number of signal(s)
mendrvERROR_PULSEBIT_IN_PROGRESS - change a signal during pulse time
mendrvERROR_CONFIGURATION – command is not applicable for MEN module or signal is not an output

mendrvCMD_WRITE_CLEAR_BIT – clear signal

This command sets a signal to its inactive state.

Argument: address of an integer value, containing the number of signal to be cleared

Return Values:

lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT – invalid number of signal(s)
mendrvERROR_STOP_TIMER – failed to stop timer for pulse bit
mendrvERROR_CONFIGURATION – command is not applicable for MEN module or signal is not an output

mendrvCMD_WRITE_CHANGE_BIT – change signal

This command changes the state of a signal.

Argument: address of an integer value, containing the number of signal to be changed.

Return Values:

lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT – invalid number of signal(s)
mendrvERROR_PULSEBIT_IN_PROGRESS - change a signal during pulse time
mendrvERROR_CONFIGURATION – command is not applicable for MEN module or signal is not an output

mendrvCMD_CHECK_PULSE_BIT – check if signal is pulsing

Argument: address of an integer value, containing the number of the signal to be checked (range 0 to 63)

Return Values:

lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT – invalid number of signal(s)
mendrvERROR_PULSEBIT_NOT_IN_PROGRESS – signal not in pulse time
mendrvERROR_CONFIGURATION – command is not applicable for MEN module or signal is not an output

mendrvCMD_WRITE_PULSE_BIT – pulse a signal

This command changes the state of a signal for a specified time.

Argument: address of an mendrvPULSE data structure with the fields

.numSignal the number of signal to pulse

.time the time in ticks to pulse the signal; the values zero gives a short pulse ( microsecond range); for longer pulses the driver will return before the pulse has terminated; a write access to this signal before the pulse has terminated will be rejected

Return Values:

lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT – invalid number of signal(s)
mendrvERROR_PULSEBIT_IN_PROGRESS – signal already pulsing
mendrvERROR_CONFIGURATION – command is not applicable for MEN module or signal is not an output
mendrvERROR_START_TIMER – failed to start internal timer

mendrvCMD_RESET_PULSE_BIT – reset pulsed signal

This command resets the timer of the pulse. The signal state will be changed.

Argument: address of an integer value, containing the signal number

Return Values:

lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT – invalid number of signal(s)
mendrvERROR_PULSEBIT_NOT_IN_PROGRESS – signal not in pulse time
mendrvERROR_CONFIGURATION – command is not applicable for MEN module or signal is not an output

mendrvCMD_NUM_DIGITAL_INPUTS – returns number of digital inputs

This command returns the number of digital inputs provided by the corresponding MEN module.

Argument: address of an integer value, where to store result.

Return Values:

lcudrvOK - successful completion

mendrvCMD_NUM_DIGITAL_OUTPUTS – returns number of digital outputs

This command returns the number of digital outputs provided by the corresponding MEN module.

Argument: address of an integer value, where to store result.

Return Values:

lcudrvOK - successful completion

mendrvCMD_SET_TTL_LATCH – configure data storage mode and trigger edge (only M58)

This command changes the data storage mode as well as the trigger edge.

Argument: address of an mendrvTTL_LATCH data structure with the fields

.mode the data storage mode; possible values are (for more detailed information see section 2.6.1)

· mendrvTTL_LATCH_MODE_NORMAL

· mendrvTTL_LATCH_MODE_TRIGGER

· mendrvTTL_LATCH_MODE_DATABUS

.edge the triggering edge; possible values are

· mendrvTTL_LATCH_EDGE_POSITIVE – rising edge

· mendrvTTL_LATCH_EDGE_NEGATIVE – falling edge

Return Values:

lcudrvOK - successful completion
mendrvERROR_CONFIGURATION – command is not applicable for MEN module or invalid input parameter

mendrvCMD_SET_TTL_TERMINATOR – enable/disable line terminator (only M58)

This command enables/disables a line terminator.

Argument: address of an mendrvTTL_TERMINATOR data structure with the fields

.port the port for which to enable the line terminator; possible values are mendrvTTL_PORT_A, mendrvTTL_PORT_B, mendrvTTL_PORT_C, mendrvTTL_PORT_D

.active the requested state of the terminator; possible values are mendrvNO_TTL_TERMINATOR, mendrvTTL_TERMINATOR_ACTIVE

Return Values:

lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT – invalid port number
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

3.3.3 Analog Module I/O Commands

mendrvCMD_GET_INPUT_CONFIG – get input signal configuration

Returns the configuration value for a specified input signal.

Argument: address of an mendrvSIGNAL_A structure, providing fields for the

.number the signal number

.config the configuration value, which will be returned by this command, where the value

mendrvCONFIG_2x10V corresponds to the input range -10 V to +10 V

mendrvCONFIG_10V corresponds to the input range 0 V to +10 V

Return Values:

lcudrvOK - successful completion
mendrvERROR_INVALID_SIGNAL_NUMBER – invalid signal number
mendrvERROR_INVALID_SIGNAL_CONFIG – signal specified is not an input signal
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_GET_OUTPUT_CONFIG – get output signal configuration

Returns the configuration value for a specified output signal.

Argument: address of an mendrvSIGNAL_A structure, providing fields for the

.number the signal number

.config the configuration value, which will be returned by this command, where the value

mendrvCONFIG_2x10V corresponds to the input range -10 V to +10 V

mendrvCONFIG_10V corresponds to the input range 0 V to +10 V

Return Values:

lcudrvOK - successful completion
mendrvERROR_INVALID_SIGNAL_NUMBER – invalid signal number
mendrvERROR_INVALID_SIGNAL_CONFIG – signal specified is not an output signal
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_SET_INPUT_CONFIG – configure input signal

With this command the signal range of an input signal is specified.

Argument: address of an mendrvSIGNAL_A structure, containing the

.number the signal number

.config the configuration value to be set, where the value

mendrvCONFIG_2x10V corresponds to the input range -10 V to +10 V

mendrvCONFIG_10V corresponds to the input range 0 V to +10 V

Return Values:

lcudrvOK - successful completion
mendrvERROR_INVALID_SIGNAL_NUMBER – invalid signal number
mendrvERROR_INVALID_SIGNAL_CONFIG – signal specified is not an input signal
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_SET_OUTPUT_CONFIG – configure output signal

With this command the signal range of an output signal is specified.

Argument: address of an mendrvSIGNAL_A structure, containing the

.number the signal number

.config the configuration value to be set, where the value

mendrvCONFIG_2x10V corresponds to the input range -10 V to +10 V

mendrvCONFIG_10V corresponds to the input range 0 V to +10 V

Return Values:

lcudrvOK - successful completion
mendrvERROR_INVALID_SIGNAL_NUMBER – invalid signal number
mendrvERROR_INVALID_SIGNAL_CONFIG – signal specified is not an output signal
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_AUTOCALIBRATION – start autocalibration (M36 only)

This command causes the board to perform autozero of each input.

Argument: none

Return Values:

lcudrvOK - successful completion
lcudrvERROR – low lever driver autocalibration routine returns an error
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_GET_GAIN – get the gain of an analog input signal

Returns the gain of a specified input signal.

Argument: address of an mendrvSIGNAL_A structure, providing fields for the

.number signal number

.gain the gain of the specified signal, which will be returned by this command

Return Values:

lcudrvOK - successful completion
mendrvERROR_INVALID_SIGNAL_NUMBER – invalid signal number
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_SET_GAIN – set gain of an analog input signal

This command sets the gain for a specified input signal. The gain factor amplifies the input signal by the given value, before it is converted to a digital value. This is to increase the resolution of the channel. The driver then divides the converted value with the gain factor to provide the true value in Volts.

Argument: address of an mendrvSIGNAL_A structure, containing the

.number signal number
.gain the gain value to be set

Values allowed are :

· mendrvGAIN_X1 - 1

· mendrvGAIN_X2 - 2

· mendrvGAIN_X4 - 4

· mendrvGAIN_X8 - 8

Return Values:

lcudrvOK - successful completion
mendrvERROR_INVALID_SIGNAL_NUMBER – invalid signal number
mendrvERROR_CONFIGURATION – command is not applicable for MEN module
mendrvERROR_INVALID_SIGNAL_GAIN – invalid gain value

mendrvCMD_READ_VALUE – read signal value

Returns the value of a specified input signal in Volts.

Argument: address of an mendrvSIGNAL_A structure, providing fields for the

.number signal number
.value to be returned by this command

.gain of the specified signal

.config configured range of the specified signal

Return Values:

lcudrvOK - successful completion
mendrvERROR_INVALID_SIGNAL_NUMBER – invalid signal number
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_READ_BIN_VALUE – read signal value in binary format

Returns the value of a specified input signal in binary format.

Argument: address of an mendrvBinSIGNAL_A structure, providing fields for the

.number signal number
.value to be returned by this command (Range: -32768/32767)

.gain of the specified signal

.config configured range of the specified signal

Return Values:

lcudrvOK - successful completion
mendrvERROR_INVALID_SIGNAL_NUMBER – invalid signal number
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_WRITE_VALUE – write value to signal

This command writes a value to the specified output signal.

Argument: address of an mendrvSIGNAL_A structure, containing the

.number signal number
.value the value to be set in Volts

Return Values:

lcudrvOK - successful completion
mendrvERROR_INVALID_SIGNAL_NUMBER – invalid signal number
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_WRITE_BIN_VALUE – write value to a signal in binary format

This command writes a value to the specified output signal.

Argument: address of an mendrvBinSIGNAL_A structure, containing the

.number signal number
.value the value to be set in integer format (Range: -32768/32767)

Return Values:

lcudrvOK - successful completion
mendrvERROR_INVALID_SIGNAL_NUMBER – invalid signal number
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_WAIT – block device (only for test purposes)

This command blocks the device for the time specified.

Argument: address to an integer defining the time to wait.

Return Values:

lcudrvOK - successful completion

mendrvCMD_NUM_ANALOG_INPUTS – returns number of analog inputs

This command returns the number of analog inputs provided by the corresponding MEN module.

Argument: address of an integer value, where to store result.

Return Values:

lcudrvOK - successful completion
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

mendrvCMD_NUM_ANALOG_OUTPUTS – returns number of analog outputs

This command returns the number of analog outputs provided by the corresponding MEN module.

Argument: address of an integer value, where to store result.

Return Values:

lcudrvOK - successful completion
mendrvERROR_CONFIGURATION – command is not applicable for MEN module

3.4 Logging

The MEN Analog and Digital I/O driver makes use of the common logging facility, i.e. the lculog module for debugging and tracing purposes. Therefore the lculog task must be loaded and spawned before the MEN Analog and Digital I/O driver is used.

The logging facility simply prints messages to the VxWorks shell. There are several different types of messages:

Errors These are printed always.
Warnings These are printed always.
Log These are printed always.
Trace These are printed only if the Trace-option is enabled.
Debug These are printed only if the Debug-option is enabled.
Interrupt These are printed only if the Intr-option is enabled.

The Intr-, Debug- and Trace-Option can be switched on by issuing the following commands to the VxWorks shell: LCU_intr, LCU_debug and LCU_trace. All functions should return the value 1.

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

3.5 Include Files

Beside VxWorks include files, driver applications must include “mendrv.h” to interface the MEN Analog and Digital I/O driver. Board dependent, this file declares as prototypes the operations provided by the driver library, and includes other files themselves.

The needed VxWorks header files

“lcudrv.h” defining the literals common to all drivers.
"mendrvErrors.h" defining the literals of the MEN Analog and Digital I/O driver errors
"mendrvCommands.h" defining the literals of the MEN Analog and Digital I/O driver commands and data

structures for multiple argument commands as used with the ioctl procedure.

3.6 Tools

The MEN Analog and Digital I/O driver includes a number of tools which can be used from the VxWorks shell. These tools are intended to be used by a system manager to ease maintenance and troubleshooting.

mendrvVersion ()
to print the version number of the mendrv driver
mendrvDevShow ()
to print the list of devices controlled by the mendrv driver with their respective base addresses, interrupt vectors and levels as well as instance of carrier board(s)
mendrvPrintDevice ( int unitNumber )
prints the status of a mendrv device in readable format; the device is specified by its unit number
mendrvPrintChannel (int fd)

Prints the status of the specified channel. The channel is identified by its VxWorks file descriptor

All the tools require that the mendrv driver is already installed and at least one device is added.

All output is made to the standard output, i.e. either to the system console or to a host terminal. Therefore the output can be redirected to a file for logging purposes.

All tools return a status code, where lcudrvOK means "successful completion" and lcudrvERROR means "ERROR".

More detailed information for the usage of the tools can be accessed through the on-line man pages.

4. Installation

The installation of the mendrv Driver is done at system start-up time by script files and shall not be changed at run-time. It is composed by the installation of the driver code, the installation of the devices for that driver and the connection of the device to the driver.

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

a standard 6U VMEbus chassis with bus backplane and power supply
at least one PPC MV2604/MV2700 CPU board
at least one MEN VME Carrier Board A201S

at least one MEN I/O Board of type M27/28, M31, M36, M37, M58
Ethernet network
LCU console (terminal attached to the serial line of the VMEbus CPU)

4.1.2 Software Requirements

VxWorks 5.4 operating system or higher
VLT Common Software APR2004 or later
the mendrv module installed on a host machine

4.2 Building the Software

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

mendrv/

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

|------src/ (source files and Makefile)

|------object/ (target dir for make)

|------doc/ (target dir for make)

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

|------bin/ (target dir for make)

|------man/ (target dir for make)

|------test/ (tat test files)

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 [3].

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

move to mendrv src directory (cd ./mendrv/src)
type ‘make clean all man install’ to

remove everything which can be made, thus enforcing recompilation of the entire code.
compile and link everything. The result, the VxWorks object-module mendrv and the installation
script mendrvInstall will be stored in directory mendrv/bin.
move the executables and include files required by external modules to their target directories.

4.3 The Installation Procedure

This section describes the steps to install the mendrv driver and the first device. A script file mendrvInstall is prepared to perform these steps. The utility vltMan can be used to access man-page information for the mendrv-functions.

4.3.2 Device Creation

The following script shall be called after installation of the driver in order to install and initialize the MEN modules available. Note that the script has to be adapted to the actual configuration.

#******************************************************************************

# E.S.O. - VLT project

# "@(#) $Id: mendrv.boot,v 1.2+ 2005/08/29 13:39:08 vltsccm Exp $"

# VxWorks script for automatic installation of driver and devices

# who when what

# -------- ---------- ----------------------------------------------

# vltcan 05.04.2005 created

LCU_trace

# Detect all M-Modules on A201 Carrier Board A16

# ----------------------------------------------

menN = lcubootAutoDevRegister("/men0", 0x2d,0x10FE,2,1,1)

menN = lcubootAutoDevRegister("/men1", 0x2d,0x12FE,2,1,1)

menN = lcubootAutoDevRegister("/men2", 0x2d,0x14FE,2,1,1)

menN = lcubootAutoDevRegister("/men3", 0x2d,0x16FE,2,1,1)

menN = lcubootAutoDevRegister("/men4", 0x2d,0x18FE,2,1,1)

menN = lcubootAutoDevRegister("/men5", 0x2d,0x1AFE,2,1,1)

menN = lcubootAutoDevRegister("/men6", 0x2d,0x1CFE,2,1,1)

menN = lcubootAutoDevRegister("/men7", 0x2d,0x1EFE,2,1,1)

menN = lcubootAutoDevRegister("/men8", 0x2d,0x20FE,2,1,1)

menN = lcubootAutoDevRegister("/men9", 0x2d,0x22FE,2,1,1)

menN = lcubootAutoDevRegister("/men10",0x2d,0x24FE,2,1,1)

menN = lcubootAutoDevRegister("/men11",0x2d,0x26FE,2,1,1)

menN = lcubootAutoDevRegister("/men12",0x2d,0x28FE,2,1,1)

menN = lcubootAutoDevRegister("/men13",0x2d,0x2AFE,2,1,1)

menN = lcubootAutoDevRegister("/men14",0x2d,0x2CFE,2,1,1)

menN = lcubootAutoDevRegister("/men15",0x2d,0x2EFE,2,1,1)

# Detect all M-Modules on A201 Carrier Board A24

# ----------------------------------------------

menN = lcubootAutoDevRegister("/men0", 0x3d,0x0110FE,2,1,1)

menN = lcubootAutoDevRegister("/men1", 0x3d,0x0112FE,2,1,1)

menN = lcubootAutoDevRegister("/men2", 0x3d,0x0114FE,2,1,1)

menN = lcubootAutoDevRegister("/men3", 0x3d,0x0116FE,2,1,1)

menN = lcubootAutoDevRegister("/men4", 0x3d,0x0118FE,2,1,1)

menN = lcubootAutoDevRegister("/men5", 0x3d,0x011AFE,2,1,1)

menN = lcubootAutoDevRegister("/men6", 0x3d,0x011CFE,2,1,1)

menN = lcubootAutoDevRegister("/men7", 0x3d,0x011EFE,2,1,1)

menN = lcubootAutoDevRegister("/men8", 0x3d,0x0120FE,2,1,1)

menN = lcubootAutoDevRegister("/men9", 0x3d,0x0122FE,2,1,1)

menN = lcubootAutoDevRegister("/men10",0x3d,0x0124FE,2,1,1)

menN = lcubootAutoDevRegister("/men11",0x3d,0x0126FE,2,1,1)

menN = lcubootAutoDevRegister("/men12",0x3d,0x0128FE,2,1,1)

menN = lcubootAutoDevRegister("/men13",0x3d,0x012AFE,2,1,1)

menN = lcubootAutoDevRegister("/men14",0x3d,0x012CFE,2,1,1)

menN = lcubootAutoDevRegister("/men15",0x3d,0x012EFE,2,1,1)

# Install driver

lcubootAutoDrvInstall "mendrv",16

# Install devices

# - uncomment as appropriate A16

#lcubootAutoDevCreate "/men0", 0x10FE,112,1,1

lcubootAutoDevCreate "/men1", 0x12FE,113,1,1

lcubootAutoDevCreate "/men2", 0x14FE,114,1,1

lcubootAutoDevCreate "/men3", 0x16FE,115,1,1

#lcubootAutoDevCreate "/men4", 0x18FE,116,1,1

#lcubootAutoDevCreate "/men5", 0x1AFE,117,1,1

#lcubootAutoDevCreate "/men6", 0x1CFE,118,1,1

#lcubootAutoDevCreate "/men7", 0x1EFE,119,1,1

#lcubootAutoDevCreate "/men8", 0x20FE,120,1,1

#lcubootAutoDevCreate "/men9", 0x22FE,121,1,1

#lcubootAutoDevCreate "/men10",0x24FE,122,1,1

#lcubootAutoDevCreate "/men11",0x26FE,123,1,1

#lcubootAutoDevCreate "/men12",0x28FE,124,1,1

#lcubootAutoDevCreate "/men13",0x2AFE,125,1,1

#lcubootAutoDevCreate "/men14",0x2CFE,126,1,1

#lcubootAutoDevCreate "/men15",0x2EFE,127,1,1

# - uncomment as appropriate A24

#lcubootAutoDevCreate "/men0", 0x0110FE,112,1,1

#lcubootAutoDevCreate "/men1", 0x0112FE,113,1,1

#lcubootAutoDevCreate "/men2", 0x0114FE,114,1,1

#lcubootAutoDevCreate "/men3", 0x0116FE,115,1,1

lcubootAutoDevCreate "/men4", 0x0118FE,116,1,1

#lcubootAutoDevCreate "/men5", 0x011AFE,117,1,1

#lcubootAutoDevCreate "/men6", 0x011CFE,118,1,1

lcubootAutoDevCreate "/men7", 0x011EFE,119,1,1

#lcubootAutoDevCreate "/men8", 0x0120FE,120,1,1

#lcubootAutoDevCreate "/men9", 0x0122FE,121,1,1

#lcubootAutoDevCreate "/men10",0x0124FE,122,1,1

#lcubootAutoDevCreate "/men11",0x0126FE,123,1,1

#lcubootAutoDevCreate "/men12",0x0128FE,124,1,1

#lcubootAutoDevCreate "/men13",0x012AFE,125,1,1

#lcubootAutoDevCreate "/men14",0x012CFE,126,1,1

#lcubootAutoDevCreate "/men15",0x012EFE,127,1,1

# Install MEN Interrupt Handler task

lcubootAutoSpawn 1,"tintMEN",20,0x8,3000,"mendrvInt"

# ___oOo___

4.4 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 have been installed correctly. From the VxWorks shell issue the following commands:

mendrvVersion
This should print the expected version number on the console.

mendrvPrintDevice(0)
This prints status and configuration information about the installed mendrv device. This information should be consistent with the configured parameters.

mendrvDevShow(0)
This should print the list of devices controlled by the mendrv driver with their respective base addresses, interrupt vectors and levels as well as instance of carrier board(s).

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.

5. Error Messages and Recovery

The driver performs a number of checks that the correct conditions are fulfilled and reports an error if this is not the case.

This section specifies the conditions the driver checks before or after the execution of a ioctl control command.

An open request in exclusive read/write mode is rejected if the device is open to any other task in exclusive or shared read/write mode.

An open request in shared read/write mode is rejected if the device is open to any other task in exclusive read/write mode.

An open request in test read/write mode is rejected if the device is open to any other task in test read/write mode.

Any check of the signal configuration, the parameter range and/or if the signal is pulsing is done before the command is executed. The ioctl command is rejected if configuration, range or status is not correct.

The following list shows all possible errors which can be returned by the mendrv driver. There are three types of errors:

VxWorks system errors
errors from the common driver library
errors from the mendrv driver

The errors are shown in alphabetical order by their literals as defined in mendrvErrors.h (mendrv specific errors with the prefix mendrv) and in lcudrvPublic.h (common errors with the prefix lcudrv) together with a description of their meaning and reason. Errors corresponding to each function are depicted in the section.

Note: Additional errors, not described here can be returned when the VxWorks I/O system rejects a call before invoking the driver.

5.1 Common Driver Errors

The following list shows common driver errors

lcudrvOK
Indicates successful completion.
lcudrvERROR
Indicates general error.
lcudrvERROR_ACCESS_CONFLICT
The open mode conflicts with the open modes of already existing channels or the requested action is not allowed with this open mode.
lcudrvERROR_CHANNEL_NOT_OPEN
The requested channel is not open.
lcudrvERROR_DEVICE_EXISTS
Attempt to create an already existing device a further time.
lcudrvERROR_DRIVER_EXISTS
Attempt to install an already existing driver a further time.
lcudrvERROR_INVALID_ARGUMENT
The value of one of the arguments was not in a valid range.
lcudrvERROR_INVALID_COMMAND
The ioctl command code matches no valid command.
lcudrvERROR_INVALID_COMMAND
The ioctl command code matches no valid command.
lcudrvERROR_INVALID_COMMAND
The ioctl command code matches no valid command.
lcudrvERROR_INVALID_DEVICE
The device name does not specify a valid device.
lcudrvERROR_INVALID_OPEN_MODE
The requested open mode is unknown.
lcudrvERROR_NO_CHANNEL
No more channel to a device is available or invalid channel number.
lcudrvERROR_NO_DRIVER
Attempt to create a device without having the driver installed yet.
lcudrvERROR_NO_MEMORY
Not enough memory available to allocate internal data structures.
lcudrvERROR_NO_MORE_CHANNEL
No more channel to a device can be opened.
lcudrvERROR_NO_SEMAPHORE
Failed to create the access protection semaphore.
lcudrvERROR_TIMEOUT
The call is timed-out because access to the device was pending for longer than the driver timeout parameter.

5.2 MENDRV Specific Errors

mendrvERROR_CONFIGURATION
Error in configuration.
mendrvERROR_INVALID_IR_LEVEL
The specified interrupt level is out of range.
mendrvERROR_INVALID_IR_NUMBER
The specified interrupt number is out of range.
mendrvERROR_INVALID_SIGNAL_CONFIG
The specified signal configuration value is out of range.
mendrvERROR_INVALID_SIGNAL_GAIN

The specified gain value is not allowed.

mendrvERROR_INVALID_SIGNAL_VALUE
The specified signal value is not allowed.
mendrvERROR_INVALID_SIGNAL_NUMBER
The specified signal number is out of range.
mendrvERROR_INVALID_TIMEOUT
The specified timeout value is out of range.
mendrvERROR_NOT_CONFIGURED
The signal to be read/written is not configured.
mendrvERROR_NOT_SETTLED
The signal to be read has not settled within the maximum timeout.
mendrvERROR_NO_EXCLUSIVE
There is no exclusive channel open on a free device command.
mendrvERROR_PULSEBIT_IN_PROGRESS
Change a signal during the pulse time.
mendrvERROR_PULSEBIT_NOT_IN_PROGRESS
Reset the pulse timer of a signal which is not in pulse time.
mendrvERROR_START_TIMER
Cannot start the command timer.
mendrvERROR_STOP_TIMER
Cannot cancel the currently running timer.
mendrvERROR_SEMAPHORE_TIMEOUT

Access to semaphore exceeded the time limit.

_______oooOOOooo_______

[1] For more detailed information see section 2.1.2 of [17]