| |
|
|
|
1 USER'S GUIDE
This part of the document provides a functional description of the module.
1.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.
1.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 [0].
The software interface of the analog I/O board consists of a set of registers to set output signals, to read input signals, to configure interrupts at the end of a conversion sequence and to get the status of the board. The board can also do autocalibration of the input signals.
The analog I/O board contains 16 input signals and 2 output signals. The board is defined as one device with 16 input and 2 output signals.
The driver supports several analog I/O board in the same system, where each board is one device. These devices share the same driver code and only have different sets of data (device descriptor tables).
1.3 User Interface to the Driver
The aio 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, specifiying the device and an open mode. The filename of a aio device is made up of two parts:
so, for instance /aio0 would specify the first aio 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 :
· 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 aio 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 aioCommands.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 [0]. 1
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 aioSet/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.
1.4 Interrupts
Two methodes are available for controlling the analog to digital conversion:
· polling, where the driver runs through a loop adapted to the duration of a analog-digital conversion sequence
· using interrupt response, whereby the board provides an interrupt at the end of each conversion sequence (EOC-Interrupt)
The EOC-Interrupt is used as default by the driver. 2
Using the interrupt mechanism can at any time be disabled or enabled with the control commands aioCMD_DISABLE_EOC_INTERRUPT respectively aioCMD_ENABLE_EOC_INTERRUPT. Only one of these methods for one device can be used, that means different adjustment of single input signals of one device is not possible.
Using interrupt response does not load the CPU like polling, but can possibly be slower than polling because of interrupt latency.
All interrupt handling is done completely inside the driver, user-defined ISRs are not necessary (and not possible).
2 REFERENCE
2.1 Introduction
This chapter provides a detailed description of the aio 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.
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 origines 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 aioErrors.h and in [8].
2.2 Functions
As mentioned in the "User Manual" part of this document, the aio driver uses the standard VxWorks I/O system calls open, close and ioctl to interface to the user. These functions are described in the following sections with respect to their special meaning in the aio context. For more general information see the "VxWorks Programmers Guide" [0].
2.2.1 open
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.
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.
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.
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.
* A value of -1 signals a general error. The specific error reason is provided in the argument status which can be
The requested open mode is conflicting with the open modes of already existing channels. This error is caused by one of the following reasons:
* Device names shall not be longer than 15 characters. They are defined by use of the function aioDevCreate at startup.
* This function is not queued by the driver, it always returns immediately with the file descriptor or an error code.
* Applications can have the same device opened several times, using different file descriptors and with different open modes.
channels is limited, applications should issue a close call if no more action on the device has to be performed.
* 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 simultanously 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.
2.2.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.
* This function is not queued by the driver, it always returns on of the above two status codes immediatly.
2.2.3 ioctl
This function commands the driver to perform the specified operation on the device. The commands are devided 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
* command is a number, identifying the operation to be performed by the driver. Literals of all commands are provided in aioCommands.h. The following commands are supported:
Read commands:
- aioCMD_GET_BOARD_ID
- aioCMD_READ_VALUE
- aioCMD_READ_BIN_VALUE
- aioCMD_GET_INPUT_CONFIG
- aioCMD_GET_OUTPUT_CONFIG
- aioCMD_GET_GAIN
- aioCMD_GET_TIMEOUT
Write commands:
- aioCMD_RESET
- aioCMD_WRITE_VALUE
- aioCMD_WRITE_BIN_VALUE
- aioCMD_SET_INPUT_CONFIG
- aioCMD_SET_OUTPUT_CONFIG
- aioCMD_SET_GAIN
- aioCMD_ENABLE_EOC_INTERRUPT
- aioCMD_DISABLE_EOC_INTERRUPT
- aioCMD_AUTOCALIBRATION
- aioCMD_SET_TIMEOUT
- aioCMD_FREE_DEVICE
- aioCMD_WAIT
* 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 aioCommands.h.
* 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.
* 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: aioCMD_SET/GET_TIMEOUT.
2.2.4 aioDrv(3)
This routine installs the AIO device driver. It is called on startup
and initializes the channel and device management. The routine must
be called before any I/O request to the driver and before installing
a AIO device.
lcudrvOK if successful completion
lcudrvERROR_DRIVER_EXISTS if driver 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
2.2.5 aioDevCreate(3)
#include "aio.h"
int aioDevCreate(char *deviceName,
int baseAddrA16,
int intrNumber,
int intrLevel,
int boardID)
This function is called at startup 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 "/aioX" X>=0, e.g. "/aio0")
baseAddrA16 - VMEbus base address of the board in the A16 short
address space [0x0000..0xffff]
(upper 16 address-bits are ignored, but should be zero)
0xffffffff: map board space into main memory for simulation
intrNumber - interrupt-vector-number of the device interrupt
intrLevel - level of the device interrupt
The interrupt-level will be enabled.
boardID - hardware board-ID to be compared, must be equal
lcudrvOK if successful completion
lcudrvERROR_NO_DRIVER if driver not yet installed
lcudrvERROR_INVALID_DEVICE if invalid device name
aioERROR_INVALID_BOARD_ID if invalid board ID
lcudrvERROR_INVALID_ARGUMENT if no board is installed at baseAddr
lcudrvERROR_DEVICE_EXISTS if device already installed
lcudrvERROR_NO_SEMAPHORE if failed to assign semaphore
lcudrvERROR_TIMEOUT if semaphore-timeout
2.3 IOCTL control 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 aioCommands.h.
The supported commands can be divided into two groups: Read and Write Commands. Read Commands are allowed in each open mode, while Write Commands are allowed only in Shared, Exclusive or Test mode.
This section describes all control commands supported by the driver, namely their purpose, arguments and return codes.
2.3.1 Read Commands
· value to be returned by this command ( .value [integer] ) );
Range: aioMIN_BIN_VALUE to aioMAX_BIN_VALUE (currently -2048/2047)
· configuration value, which will be returned by this command ( .config [integer] ), where the value
· configuration value, which will be returned by this command ( .config [integer] ), where the value:
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.
2.3.2 Write Commands
· the value to be set in integer format( .value [integerl] );
Range: aioMIN_BIN_VALUE - aioMAX_BIN_VALUE (currently -2048/2047)
With this command the signal range of an input signal is specified. Note that the configuration is defined by jumper settings on the board [3], it is not programmable. This command is only to inform the driver about the jumper selection.
This command sets the output signal range. Note that the configuration is defined by jumper settings on the board [3], it is not programmable. This command is only to inform the driver about the jumper selection.
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.
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.
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.
2.4 Include files
Applications using the aio must include aio.h. The aio.h include file includes everything required to use the procedures described in the previous section.
· "aioCommands.h" which defines literals of the aio Driver commands and the data structures for multiple argument commands as used with the ioctl procedure.
2.5 Tools
The aio 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.
· aioDevShow ()
to print the list of devices controlled by the aio driver with their respective base addresses
· aioPrintRegs ( unitNumber )
prints the device register contents in readable format, the device is specified by its unit number
· aioPrintDevice ( unitNumber )
prints the status of a aio device in readable format, the device is specified by its unit number
All the tools require that the aio 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.
3 INSTALLATION
The installation of the aio 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.
3.1 Installation Prerequisites
The following hardware and software prerequisities must be fulfilled for a successful installation of the driver.
3.1.1 Hardware Requirements
3.1.2 Software Requirements
3.2 Building the Software
The aio module is delivered as a UNIX tar file, either on disk or on tape. The file expands in a directory structure as defined in [2].
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 [5].
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 [2] 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:
b. compile and link everything. The result, the VxWorks object-module aio and the installation script aioInstall will be stored in directory aio/bin.
3.3 Installation Procedure
This section describes the steps to install the aio driver and the first device. A script file aioInstall is prepared to perform these steps. The utility vltMan can be used to access man-page informations for the aio-functions.
2. The driver is installed by invoking the function aioDrv() with the following parameters (see Reference):
3. A device is installed by invoking the function aioDevCreate() with the following parameters (see Reference):
· the device name: "/aio<i>" where <i> is the device unit number, starting with 0 and incrementing by one for each additional device.
5. Connects the device to the driver (enabling interrupts, defining vector number, connecting Driver ISR).
An installation script file aioInstall is prepared in directory <drvRoot>/aio/bin which performs the above described installation procedure with default parameters. It is strongly recommended to use this script only to install the aio driver. A listing of the installation script is provided in the following section. To install the aio driver do the following from the VxWorks shell of the target system:
· putenv "VWROOT=<drvRoot>") to set the environment variable VWROOT; <drvRoot> is the root directory into which the module aio is installed
3.4 Installation Script Example
The following installation script shall be called at system start-up time either included in a system start-up file or called from here.
#************************************************************************
# NAME
# aioInstall - install the AIO driver and device on target LCU
#
# SYNOPSIS
# aioInstall
#
# DESCRIPTION
# This script is used to load the AIO driver module object from the host
# to the LCU target system and to configure the driver. This script must
# run on the LCU target system under the VxWorks shell.
#
# FILES
# aio must exist on the host system with group read access
#
# ENVIRONMENT
# The environment variable VWROOT can be set to the LCU drivers
# directory using the VxWorks function putenv("VWROOT=.......").
# The driver module is taken from $VWROOT/bin.
# If VWROOT is undefined then ./bin is used.
#
# RETURN VALUES
# none
#
# CAUTIONS
# This script must be run only once, at LCU system start-up time
#
# EXAMPLES
# vxworks> cd "/vlt/vw"
# vxworks> < bin/aioInstall
#
# SEE ALSO
# AIO Driver User Manual
#
#------------------------------------------------------------------------
#
# load driver object
cd getenv("VWROOT")
cd "bin"
ld < aio
cd ".."
# install and configure the AIO driver
aioDrv(1,10,100)
# install and configure the AIO device
aioDevCreate("/aio0", 0xffff8000, 65, 1, 0x0d)
3.5 Installation Verification
Functions performed during installation phase always log OK or ERROR messages to the console.
The tools described in a previous section can be used to test that the driver and the device have been installed correctly. From the VxWorks shell issue the following commands:
· aioPrintDevice(0)
This prints status and configuration information about the installed aio device. This information should be consistent with the configured parameters.
· aioPrintRegs(0)
This should dump the register contents of the specified device unit on the console. The values are from minor interest but the fact that this command causes no bus error indicates that the device registers are probably mapped correctly.
4 ERROR MESSAGES AND RECOVERY
The following list shows all possible errors which can be returned by the aio driver. There are three types of errors:
The errors are shown in alphabetical order by their literals as defined in aioErrors.h (aio specific errors with the prefix aio) and and in [8] (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 2.2.
Note: Additional errors, not described here can be returned when the VxWorks I/O system rejects a call before invoking the driver.
4.1 Common Driver Errors
The following list shows common driver errors as defined in [8].
· 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_TIMEOUT
The call is timed-out because access to the device was pending for longer than the driver timeout parameter.
4.2 aio specific Errors
1There should be one semaphore per device, but up to version 1.19 of the driver there is only one semaphore for all devices controlled by the aio driver. This means that there might be more blocking than necessary.
3Note: Before driver version 1.3 the argument was passed by value, not by reference through a pointer. However, the User Manual always stated it this way. Now code and manual are consistent.
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|