| |
|
|
|
2 USER'S GUIDE
This part of the document provides a functional description of the module: how to use it and what to use it for.
2.1 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 [1].
The software interface to the digital I/O board 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 digital I/O board contains 64 I/O signals, which can all be configured as input or output. The board is defined as one device with 64 I/O signals. The digital I/O board is described in [4].
The first 8 signals can be configured to interrupt on a specified state. The interrupts are not completely handled by the driver as the driver cannot send asynchronous messages. Instead the user has to supply a routine to handle the interrupts. This routine is invoked by the driver when an interrupt occurs together with an indication which signal(s) caused the request. It is running in task mode and not in interrupt mode, see also [1]. The driver disables the interrupt before calling this routine. It is also possible to specify a parameter to be sent to the routine on an interrupt.
The driver supplies commands to manage the interrupt source (the digital I/O board). The user routine shall not do any direct accesses to the digital I/O board hardware, but shall use the commands to the driver. The hardware interrupt handling is described in [1].
The driver supports several digital I/O boards 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 descriptors).
2.2 Driver Functions
This driver implements basically the functionality of the Digital I/O board but combines some elementary function with VxWorks OS features to more complex ones. However, the software using the driver has the maximum flexibility available.
The driver conforms to the VxWorks driver concept, i.e. it supports the functions open, close and ioctl.
The open and close calls are used to specify or free a channel to get and regulate access to the device. The filename is specifying the device to which the channel shall be opened and is made up of two parts:
Write accesses are only permitted to the task which has opened the device in read/write mode, while read accesses are not restricted.
The read and write calls are only empty routines to conform to the standard driver interface, [1].
All functions performed by the Digital I/O board are activated with the ioctl call. The ioctl call has a parameter specifying the action requested by the driver. This parameter is in this document called ioctl control command. 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.
Before a task has performed an open call it can not send any read or write command to the driver.
The driver controls the access of the device, provided by the open/close calls giving the following possibilities (read accesses are always permitted for a task which has opened the device in read or read/write mode):
2. 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.
3. 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.
4. 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 task. 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.
In addition, the driver calls are mutually exclusive, i.e. the device accessed by a task is protected from access from any other authorized task until the executing driver call has terminated. This means that if a task is executing a driver call and another task tries to access the driver for the same device, then this second task will be blocked until the driver call of the first one has terminated. The blocked task will be put on a queue. There is one queue for each device and the tasks on the queue will be scheduled according to their priority. The implementation of the driver uses the VxWorks mutex semaphore for this functionality and to provide priority inheritance, see reference [1].
A task blocked for access of a device will have a timeout.
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 task can interfere during the action. Section 5.1 defines for which Ioctl commands the access checks are performed. The open call returns a file handle with which the channel is identified in any further driver calls.
3 REFERENCE
3.1 Introduction
This chapter provides a detailed description of the Acromag 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.
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 acroErrors.h and in [9].
3.2 Functions
As mentioned above, the Acromag Digital I/O 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 Acromag Digital I/O driver context. For more general information see the VxWorks Programmers Guide [1].
3.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 accesses are always granted for any open modes.
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 Shareable write mode returns an error.
Test read and write open mode. Write access is granted to the task using this open 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:
* 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 acroDevCreate at startup.
* The number of opened channels for all devices of the driver is limited to the value defined at installation-time.
* 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.
* 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
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.
3.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 an integer, identifying an Acromag Digital I/O command to be sent to the driver. The values identifying a command are defined in the include file acroCommands.h.
* argument is the address of the command argument, or NULL if no argument is used. For `Write' commands, argument contains the values to be written, for `Read' commands, the value read is returned in argument.
Argument, when used, can only be an integer, or structures defined in the include file acroCommands.h provided by driver libraries and described in section "Ioctl control commands".
* 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.
* Other specific values returned by the driver are described for each ioctl command in section 3.3 and a full description of errors can be found in chapter 5.
* A cast to (int) for the third parameter is necessary because the declaration in VxWorks overrides the one shown here.
* This function is protected by a semaphore, and commands are queued by application priorities rather than by First-in First-out.
* A timeout is implemented to ensure the permissible maximum blockingdelay of a task. This delay, expressed in ticks (currently there are 100 ticks in 1 second), is initialized at start-up, and can be read or modified at run-time by two additional commands (get/set timeout).
3.2.4 acroDrv(3)
This function is called only once at startup. It hooks up the various
I/O service calls to the diver's functions, assigns the driver number,
and adds the driver to the driver table.
devices - number of supported devices
channels - number of channels that can be simultanously be opened
timeout - access timeout value
lcudrvOK - driver successfully installed
lcudrvERROR_DRIVER_EXISTS - the driver is already installed
lcudrvERROR_NO_MEMORY - there is not enough memory for dynamic
data structures
lcudrvERROR_INVALID_ARGUMENT - the value of one of the parameters is
out of range
3.2.5 acroDevCreate(3
#include "acro.h"
int acroDevCreate(char *devName,
void *baseAddrA16,
int intrNumber,
int intrLevel)
This function is called at startup 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 "/acroX" X>=0, e.g. "/acro0")
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.
lcudrvOK - successful completion
lcudrvERROR - there is a general VxWorks I/O error
lcudrvERROR_NO_DRIVER - driver not yet installed
lcudrvERROR_INVALID_DEVICE - invalid device name
lcudrvERROR_INVALID_ARGUMENT - invalid parameter
lcudrvERROR_DEVICE_EXISTS - device already installed
lcudrvERROR_NO_SEMAPHORE - creation of access protection semaphore
failed
int status;
status = acroDevCreate("/acro0", 0x1000, 0xb0, 2);
if (status != lcudrvOK)
{
// error process
}
3.2.6 acroPulsebitMicrosecSet(3)
STATUS acroPulsebitMicrosecSet (char *deviceName, int microsec)
#include "acro.h"
#include "acroDevice.h"
This function sets the pulse duration in microsec when the time
parameter of the pulse command is zero.
deviceName - name of device
microsec - pulse duration
3.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 acroCommands.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 lists all control commands supported by the driver. The list also contains a short description of each command and its literal. The error codes sent in case of an error are described in Chapter 5.
3.3.1 Ioctl Read I/O Commands
This command returns the states of the specified input signal(s). One signal or several consecutive signals. If more than 8 signals are read, they shall preferably be aligned to a port (8 signals), i.e. starting with signal number 0 or 8 or 16 etc.
· .numSignal (in) the number of signals (range 1 to 32); the sum of the number of the first signal and number of signals must be less than or equal to 64
· .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.
This command returns the configuration of the specified signal(s). One signal or several consecutive signals.
· .numSignal (in) the number of signals (range 1 to 32); the sum of the number of the first signal and number of signals must be less than or equal to 64
· .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.
Argument: address of an integer value, containing the number of the signal to be checked (range 0 to 63)
3.3.2 Ioctl Write I/O Commands
· .numSignal the number of signals (range 1 to 32); the sum of the number of the first signal and number of signals must be less than or equal to 64
· .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.
This command writes a value to the signal(s) specified. One signal or several consecutive signals. If more than 8 signals are read, they shall preferably be aligned to a port (8 signals), i.e. starting with signal number 0 or 8 or 16 etc.
· .numSignal the number of signals (range 1 to 32); the sum of the number of the first signal and number of signals must be less than or equal to 64
· .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.
· .numSignal the number of signals (range 1 to 32); the sum of the number of the first signal and number of signals must be less than or equal to 64
· .value the time in ticks to pulse the signal; the values zero gives a short pulse ( microsecond range, see acroPulsebitMicrosecSet(), 3.2.6 and table below); 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
Pulse with value 0 to acroCMD_WRITE_PULSE_BIT will give the following length of the pulse (acroPulsebitMicrosecSet() with value 0)
The table below shows the lenght of the pulse when the function acroPulsebitMicrosecSet() is used for the corresponding value for the different standard CPUs.
3.3.3 Ioctl Interrupt Commands
This command enables 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.
· .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.
This command clears the interrupt status bit for a signal. This is only feasible in polling applications for a disabled interrupt signal, because otherwise the internal driver ISR will try to clear the request automatically. Note that the interrupt stimulus must be removed from the signal before the status bit can be cleared.
· acroERROR_INTERRUPT_NOT_CLEARED - the status bit cannot be cleared because the stimulus is still active
Returns the interrupt status as a bit vector. All signals which are in the interrupting state (whether enabled or not) are indicated by `1' bits. Bit positions 0 to 7 refer to signal numbers 0 to 7. This command is only feasible in polling applications for disabled
interrupt signals, because otherwise the internal driver ISR will clear the request automatically before it can be read.
3.3.4 Ioctl General Commands
The purpose of this command is to freethe device when a task which has opened the device in exclusive read/write mode is blocked or has terminated without closing the device. In this case it is not possible to send a write command to the device. This command frees the device and enables another task to open the device in read/write mode. The intention is that this command shall only be used `manually' by an operator, to free the device and should not be used by tasks which wants to send ioctl write commands to the device.
3.4 Logging
The Acromag Digital I/O driver makes use of the common logging facility, i.e. the lculog module for debugging and tracing purposes. Therefore the lculog taskmust be loaded and spawned before the Acromag digital I/O driver is used.
The logging facility simply prints messages to the VxWorks shell. There are several different types of messages:
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 Interrupts
The first 8 of the 64 signals can be configured to interrupt if their states are active or inactive.
Interrupts can be enabled or disabled by the commands acroCMD_ENABLE_INTERRUPT and acroCMD_DISABLE_INTERRUPT for each of the 8 signals 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 {\em 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 acroCMD_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 8 interrupts and is executed in task mode (namely in the context of the driver provided interrupt task), not in interrupt mode.
The 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 7 to signal 7. A `1' bit indicates that an interrupt is pending from the corresponding signal.
When an interrupt occurs from a signal, it will be disabled automatically for this specific source by the driver. The enable status of all other signals remain unchanged. Note that the User-ISR has not to deal with clearing the interrupt request in the Digital I/O board. However, as long as the corresponding signal is still in the interrupting state, a further interrupt will occur immediately upon re-enable!
Either one has to wait until the signal goes to the non-interrupting state before a re-enable can be done, or the definition of the interrupting state must be changed with the re-enable. For hardware reasons there is no other way to handle this situation.
An example of a User-ISR is and its installation:
* User-ISR logs a message on every state change of signal 0
void acroUserIsr(int parameter, u_char pendingMask)
logMsg("\n--- ACRO Interrupt: par=%d, mask=0x%02x ---\n",
parameter,pendingMask,0,0,0,0);
* Invert the polarity and re-enable:
(void)ioctl(acroFd, acroCMD_ENABLE_INTERRUPT, (int)&argEna);
acroFd = open("/acro0", lcudrvOPEN_SHARED, (int)&status);
if (acroFd < 0) return(status);
status = ioctl(acroFd, acroCMD_CONFIG_INTERRUPT, (int)&argCfg);
if (status != lcudrvOK) return(status);
* Enable signal 0 to interrupt when it is in active state
status = ioctl(acroFd, acroCMD_ENABLE_INTERRUPT, (int)&argEna);
if (status != lcudrvOK) return(status);
The following two commands are especially useful for applications which poll signals with interrupt disabled.
The command acroCMD_READ_INTERRUPT_STATUS returns all signals for which an interrupting state has been detected and not yet cleared. Note that for signals, for which the interrupt was enabled, the internal driver ISR might have already cleared the request.
The command acroCMD_CLEAR_INTERRUPT tries to clear a pending interrupt request for a signal. However, it cannot be cleared if the signal is still in the interrupting state!
3.6 Include files
Beside VxWorks include files, driver applications must include "acro.h" to interface the Acromag Digital I/O driver. Board dependent, this file declares as prototypes the operations provided by the driver library, and includes other files themselves.
· "acroCommands.h" defining the literals of the Acromag Digital I/O driver commands and data structures for multiple argument commands as used with the ioctl procedure.
3.7 Tools
The Acromag 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.
· acroConfig (unitNumber)
prints the configuration data structure for the device specified by unitNumber
· acroReg ( unitNumber )
prints the device register contents whereby the device is specified by its unitNumber
All the tools require that the Acromag Digital I/O driver is already installed and at least one device is added.
All output is made on the standard output, i.e. either to the system console or to a host terminal.
The following section contains the man-page for the tools.
3.7.1 acroTools(1)
#include "acro.h"
void acroVersion(void)
void acroDevShow(void)
void acroSt(int unit)
void acroConfig(int unit)
void acroReg(int unit)
void acroErrorPrint(int err)
void acroSizeofPrint(void)
void acroTbl(void)
Tool functions providing information about a Acromag Digital I/O device
and driver.
acroVersion - print the driver version
Prints a string in the form "ACRO Device Driver, Version 1.4.0"
acroDevShow - print a list of devices controlled by the driver
Prints a list in the form "/acro0 at base-address 0xffff1000"
acroSt - print the global device status information
Prints the contents of the status/control register of the specified
Acromag Digital I/O device.
acroConfig - print the device configuration information
Prints configuration information for all signals of the specified
Acromag Digital I/O device.
acroReg - print the register data structure
Prints the register contents of the specified device.
acroErrorPrint - print the error message of an error code
Prints the error message corresponding to the specified error code.
acroSizeofPrint - print the data structure sizes
Prints the sizes of the driver data structures in bytes.
acroTbl - print the command table:
By call of this function a summary of the Acromag Digital I/O drivers
command table is printed. It contains information about the command
number, protection requirements and the address of the command handler.
No error checking will be done. Be sure that the Acromag Digital I/O
driver is already installed when using this function.
4 INSTALLATION GUIDE
The installation of the {\bf acro} driver is done at startup by script files and shall not be changed at run_time. It is composed by the installation of the driver code, common to all devices using the same board type, the installation of the devices corresponding to each driver, and the connection of interrupts, to vector numbers and interrupt service routines.
This section describes how to build the acro software, if executables are not already available. It then describes step by step the boot script file to load the software on the target. Finally test procedures to verify the installation are described.
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
4.1.2 Software Requirements
4.2 Building the Software
The acro module is delivered as a UNIX tar file, either on disk or on tape. The file expands in a directory structure as defined in [3].
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 [6].
Before using the Makefile 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 [3] 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 acro and the installation script acro.boot will be stored in directory acro/bin.
4.3 Installation Procedure
This section describes the steps to install the acro driver and the first device. A script file acro.boot is prepared to perform these steps. The utility vltMan can be used to access man-page informations for the acro-functions. Install the acro module with the tool vccConfigLcu in your LCU environment (bootScript).
2. The driver is installed by invoking the function acroDrv() with the following parameters (see Reference):
3. A device is installed by invoking the function acroDevCreate() with the following parameters (see Reference):
· the device name: "/acro<i>" where <i> is the device unit number, starting with 0 and incrementing by one for each additional device.
Applications using interrupts shall supply their own ISRs. All interrupts will be executed under the Acromag Digital I/O interrupt task.
4. Spawn the Acromag Digital I/O interrupt task. This task is currently defined to have a priority of 200 and a stack of 2000 bytes.
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:
· acroReg(0)
This should dump the register contents of the installed device 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.
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
5.1 Error Checking
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.
The Ioctl control commands are shown in two tables below, one for read commands and one for write commands. The tables shows under which conditions ioctl commands are accepted and executed.
The check of the signal configuration, the parameter range and 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 acro driver. There are three types of errors:
The errors are shown in alphabetical order by their literals as defined in acroErrors.h (acro specific errors with the prefix acro) 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 3.2.
Note: Additional errors, not described here can be returned when the VxWorks I/O system rejects a call before invoking the driver.
5.1.1 Common Driver Errors
The following list shows common driver errors as defined in [9].
· 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.
5.1.2 acro specific Errors
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|