3 DRIVER FUNCTIONS

3.1 Introduction

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

· rmnDrv to install the rmn driver

· rmnDevCreate to add a rmn device to the driver

· open to open a channel to a device

· close to close a channel

· ioctl to issue a control command

Each of these calls returns a status code which signals the success of the call. A zero value always means "successful completion" while a negative value indicates an error. The value -1 stands for "general error" and origins in VxWorks while other values signal a specific error reason and are returned by the driver itself. Literals of all error codes can be found in the include file rmnErrors.h and in [7].

3.2 Driver and Device Installation Functions

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

1. rmnDrv to install the driver, which takes the arguments:

a. the maximum number of supported devices

b. the maximum number of supported channels to devices

c. a timeout value for semaphore waits

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

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

b. the base-address of the board in the VMEbus A24 or A32 address-space. The value 0xffffffff will create the device in simulation mode¹.

c. the address-space selection (rmnVME_ADD_A24 or rmnVME_ADD_A32)

d. the memory option (rmnMEM_256KB, rmnMEM_512KB or rmnMEM_1MB)

e. the interrupt-vector number of the first interrupt source (64..252)²

f. the interrupt-level number (1..7)³

The parameters b., c. and d. must be chosen according to the jumper settings made on the board and to the actual amount of memory installed. Standardized base addresses, interrupt vectors and interrupt level are defined in the VLT standard VME boards configuration [8]. All the arguments are stored in the device-descriptor.

The driver performs the following steps at device installation during rmnDevCreate() and report any error or exceptional situation to the caller:

· Check that the address-space is correctly specified.

· Check that the memory option is correctly specified.

· Check that the interrupt vector is in the proper range.

· Check that the interrupt level is in the proper range.

· Check if the driver has been installed.

· Validate the given device-name.

· Get the base address of the board in the CPU address space (CPU local address).

· In case of simulation mode, allocate the required memory.

· Verify if the base-address is correct, check if the reflective memory board is present at that address, perform a test of the board's memory.

· Initialize the device-specific data structures, add the device to VxWorks, and allocate the access protection semaphore.

*** from here on the device is installed under VxWorks ***

· Configure and initialize the interrupt sources (interrupt vectors, interrupt level, internal hooks
and data structures for user-provided ISRs).

· Reset (switch off) the Fail LED on the front panel to give a visual feedback that the device has been created and initialized successfully

After an OK return, the device is correctly installed under VxWorks and ready to accept open calls.

3.3 Tool Functions

The following tool functions are provided:

· rmnVersion to print the version of the loaded driver module to the LCU console;

· rmnDevShow to print a list of all installed devices with their respective installation parameters to the LCU console;

· rmnDevDump(<device>) to print the content of the board's registers in a convenient format to the LCU console;

· rmnMemDump(<device>) to print the content of the board's register in hexadecimal format to the LCU console;

· rmnDevDescrDump(<device>) to print the content of the device descriptor data structure to the LCU console;

· rmnTestBoard(<device>) to perform a test of the board and of the optical link; it is the tool-function implementation of the corresponding ioctl-command "Test Board and Link" (see § 4.3).

3.4 Device Access Functions

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

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

a. device-name

b. open-mode

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

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

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

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

a. the file-descriptor as returned by open

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

c. a pointer to an argument value, whereby values can also be returned

It returns an error-code (integer).

4. read and write - as well as other standard VxWorks driver functions - are not necessary and not supported.

These functions are described in the following sections with respect to their special meaning in the rmn context.

See also the man-pages of the internally used device-specific routines in the Reference chapter 9 for detailed information, especially for an exact error reference. For more general information see the "VxWorks Programmers Guide".

3.4.1 open

NAME

open - open a channel to a rmn device

SYNOPSIS

#include "rmn.h"

int open (char *deviceName, int openMode, int *status)⁴

DESCRIPTION

This operation opens the device corresponding to deviceName in read-only mode or in one of the read/write modes described below. The read access is granted in all open modes. The argument status receives the completion status of the routine.

* deviceName specifies the device (e.g. "/rmn0")

* openMode can be:

-lcudrvOPEN_READONLY

Read only mode.

-lcudrvOPEN_SHARED

Shareable read and write mode. Write access is granted to a defined number of tasks to use this open mode. Exceeding this number or requesting this mode for a device already opened in Exclusive mode returns an error.

-lcudrvOPEN_EXCLUSIVE

Exclusive read write mode. Write access is granted to the task using this open mode. Requesting this mode for a device already opened in Exclusive or Shared mode returns an error.

-lcudrvOPEN_TEST

Test read and write open mode. Write access is granted to the task using this option mode regardless of the status of the device. Requesting this mode for a device already opened in Test mode returns an error.

*status is a pointer to the error-code to be returned. If it is NULL, then nothing is returned. Note that this value is only valid when the function's return-value actually indicates an error.

RETURN VALUES

* A positive file descriptor number, which must be used for subsequent close and ioctl operations.

* A value of -1 signals a general error. The specific error reason is provided in the argument status, as stated in the man-pages of the rmnOpen device-specific routine § 9.5.

* The zero value is never returned.

EXAMPLE

int fd, status;

......

fd = open ("/rmn0", lcudrvOPEN_READONLY, (int)&status);

if (fd <= 0)

{

/* error processing */

......

}

else

{

/* normal processing */

......

}

CAUTIONS

* Device names shall not be longer than 15 characters. They are defined by use of the function rmnDevCreate at startup.

* This function is not queued by the driver, it always returns immediately with the file descriptor or an error code.

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

* Applications can have the same device opened several times, using different file descriptors and with different open modes.

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

* 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.4.2 close

NAME

close - close a channel to a rmn device

SYNOPSIS

#include "rmn.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 as stated in the man-page of the rmnClose device-specific routine § 9.1.

EXAMPLE

int fd, status;

int closeError;

fd = open ("/rmn0", 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 one of the above status codes immediately.

3.4.3 ioctl

NAME

ioctl - send a control command to a rmn device

SYNOPSIS

#include "rmn.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 rmnCommands.h. and described in chapter 4.

* 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 rmnCommands.h.

RETURN VALUES

* lcudrvOK if the command is successfully transmitted and performed by the device.

* errors as stated in the man-pages of the rmnIoctl device-specific routine and in each command's description in chapter 4.

EXAMPLE

int fd, status;

int arg;

int ioctlError;

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

......

arg = 30;

ioctlError = ioctl (fd, rmnCMD_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.

¹

See § 4.6 for more details about simulation.

²

The interrupt-vector is defined only for the first interrupt source. The remaining 3 interrupt sources will be connected to progressively increasing interrupt-vectors.

³

The same interrupt level is assigned to all the 4 interrupt sources.

⁴

Note that the third parameter is declared as (int) in VxWorks. A cast with (int) will therefore always be necessary when this function is called.

⁵

Note that the third parameter is declared as (int) in VxWorks. A cast with (int) will therefore always be necessary when this function is called.

Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com