2 OVERVIEW

This manual covers the device-specific part for the VME-ISER8. For a general overview about drivers and devices, refer to the Driver Development Guide [7].

2.1 The Hardware

The VME-ISER8 is an intelligent interface board which provides 10 serial interfaces and two additional ports for programming and service purposes. The transfer frame of each serial channel can be separately selected between 5 and 8 bits with a parity bit as an option. For each channel software or hardware handshake can be selected.

2.2 The Driver

This driver implements the functionality of the VME-ISER8, that is it gives the same functionality as the board and does not combine elementary functions to more complex functions. This is left by purpose to the software using the driver in order to achieve the maximum flexibility.

2.3 The Devices

Each board is mapped to 10 devices, one per channel. As recommended in [7], the device-names are derived from the module-name "iser", i.e. the devices must be named "/iser0", "/iser1", etc.

The driver controls 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.

2.4 Device Access

The driver conforms to the VxWorks driver concept, that is it supports the functions open, close, ioctl, read and write. It also provides the recommended installation functions. See section 3.

Ioctl commands directly accessing a register do not have any protection from simultaneous access as the command is executed by an immediate action, that is in one non-interruptible instruction. In this case there is no need for any protection as no other process can interfere during the action.

2.5 Interrupts

The VME-ISER8 occupies twenty interrupt-vectors (236 to 255) at interrupt-level 1. These values are hard-coded in the driver, and therefore not user configurable.

2.6 Include files

Applications using the iser must include iser.h, sometimes also tyLib.h. The iser.h include file includes everything required to use the procedures described in the previous section.

· "iserCommands.h" which defines literals of the iser Driver commands and the data structures for multiple argument commands as used with the ioctl procedure.

3 DRIVER FUNCTIONS

3.1 Introduction

This chapter provides a detailed description of the iser 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.

· iserDevCreate to add a iser device to the driver

Each of these calls returns ERROR or OK signaling the success of the call, in case of error errno is also set.

3.2 Driver and Device Installation Functions

The installation of the ISER driver is according to the VxWorks driver concept described in [3] and [4]. Two functions are provided:

2. iserDevCreate to install a device, which takes the arguments:

a. the device-name (which must be /iser<number>, with <number> starting from zero)

b. the device-channel, which is thePhysical channel for this device (0 up to 9)

If the device was already created or the device inialization is not successful ERROR is returned.

3.3 Device Access Functions

The standard VxWorks functions as described in [3] and [4] are used to request and release access to an ISER8 device. Driver-specific functions are connected to these calls upon driver installation:

1. open to get access to a device. It takes the arguments:

c. pointer to an error-code (integer) to be returned

It returns a file-descriptor (positive integer) or ERROR.

The second and third arguments are not really used.

2. close to release access to a device. It takes as argument the file-descriptor.

3. read to read bytes from the serial device. It takes the argumets:

b. pointer to the buffer where to placethe bytes read

4. write to write bytes to the serial device. It takes the argumets:

b. pointer to the buffer with the data that is going to be written

5. ioctl to send commands to and query values from a device. It takes the arguments:

b. the ioctl-command, an integer value as described in section 3.4

c. In most cases of ioctl commands to this driver this parameter is the actual argument by value. In some cases, like the command FIONREAD, which are handled by the underlying tyLib, this parameter is a pointer to the data returned.

3.3.1 open

int open (char *deviceName, int openMode, int mode)

3.3.2 close

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.

3.3.3 ioctl

ioctl - send a control command to a iser device

int ioctl (int fileDescriptor, int command, int arg)

3.4 DRIVER 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. In most cases of ioctl commands to this driver, including all cases in the command table below, the third/last parameter is the actual argument by value, which is also tabulated. In some cases, like the command FIONREAD, which are handled by the underlying tyLib, this parameter is a pointer to the data returned.

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

Each ioctl-command can have an argument, which can consist of one scalar or a struct of more values of type integer resp. double, other types are not allowed.

A pointer to the argument is passed in the ioctl call, never the argument value itself. The ioctl function returns values through this pointer.

This driver responds to all the same ioctl codes as a normal ty driver. The baud rates available are normally 50, 75, 110, 150, 300, 600, 1200, 2400, 4800, 9600, 19200 and 38400. For the upper 2 channels ( 8 & 9 ) are also 76800 and 115200 Baud available. If none if these is written, the ISER takes the nearest one, which is available (refer to the ISER-manual ).

Additionally it is possible, to set character-length, number of stopbits, parity-mode and special for ISER-applications handshake-mode, rx-mode and rx-record-length. To do this, there are additional defines in iserCommands.h with following meanings:


COMMAND	ARGUMENTS	ACTION
FIOCHARLEN	5...8	set characterlength to 5...8 bit In case of Error (Return -1)
FIOSTOPBIT	1 or 2	set number of stopbits In case of Error (Return -1)
FIOPARITY	>0 =0 <0	set even parity set no parity set odd parity
FIOHNDSHK	0 1 2 3 4 5	Hardware-handshake DTR/CTS Software-handshake XON/XOFF Modem-handshake RTS/CTS no handshake RS-485-operation, no handshake RS-422-operation, XON/XOFF-handshake In case of Error (Return -1)
FIORECLEN	0 1..1024	use maximal record-length (=1024) definable record-length In case of Error (Return -1)
FIORXMODE	1 2 4 0 < 0	Use specified char as end condition (addable). e.g. 7 = EOT + LF + CR. EOT (end of text) LF (line feed) CR (carriage return) use only record-length as end-condition binary mode, no end-condition, no XON/XOFF In case of Error (Return -1)
FIOTIMOUT0	0 1..32767	no timeout to receipt of first character timeout to receipt of first character (milliseconds)
FIOTIMOUT1	0 1..32767	no timeout to time beteen receipt of further characters timeout to time between receipt of further characters (milliseconds)

The end-condition means the condition, on which the ISER transmits the received characters to the master. Such an end-condition may be one of the above character (if defined), a timeout or the defined record-length. So if you define a record-length of 1, the ISER works like a normal UART.

There is no timeout for sending/transmitting characters and this cannot be modified by this driver. Note the the ISER8 hardware sets FIOTIMOUT0 and FIOTIMOUT1 back to 0 after each transmission/receipt.

4 INSTALLATION

The installation of the iser 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 prerequisities must be fulfilled for a successful installation of the driver.

4.1.1 Hardware Requirements

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

· a VMEbus chassis with bus backplane and power supply

· one Motorola MVME167 or MVME2604 CPU board, any version

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

4.1.2 Software Requirements

· VxWorks version 5.2 or 5.3.1 operating system

· the iser module installed on a host machine

4.2 Building the Software

The make procedure follows VLT standards, as described in [5] and [6]. In short:

The loadable binary file iser will be stored in "$INTROOT/vw/bin/" (if defined) respectively "$VLTROOT/vw/bin/".

4.3 Installation Procedure

This section shows an example to install the iser driver and the first device. The utility vltMan can be used to access man-page informations for the iser-functions.

1. Load the iser driver code to the target system:
-> ld < root-path/vw/bin/iser

3. Install the first device:
-> iserDevCreate("/iser0", 0, 512, 512)