ICS-121. VxWORKS DEVICE DRIVER MANUAL

ICS-121 VxWORKS DEVICE DRIVER MANUAL Interactive Circuits And Systems Ltd. February 1999 The information in this manual has been carefully checked and is believed to be reliable; however, no responsibility is assumed for possible inaccuracies or omissions. Interactive Circuits and Systems Ltd. reserves the right to make changes to products herein described to improve reliability, function, or design. No patent rights are granted to any of the circuits described herein. Extra copies of this manual are available from the factory. ICS Ltd 5430 Canotek Road Gloucester, Ontario K1J 9G2 Canada Tel: (613) 749-9241 USA: (800) 267-9794 Fax: (613) 749-9461 E10540 REV.A

TABLE OF CONTENTS 1 INTRODUCTION 1 1.1 Related Documents 1 2 INSTALLATION GUIDE 2 2.1 Installing the ICS-121 2 2.2 Installing the ICS-121 Device Driver Software 3 2.3 Using the ICS-121 Device Driver 4 3 PROGRAMMING GUIDE 5 3.1 Driver Initialization Functions 5 ics121drv Initialize ICS-121 Driver 5 ics121devcreate() Add ICS-121 board to device list 5 3.2 Dynamic Installation of ICS-121 Device Driver at Run Time 7 3.3 Opening and Closing the ICS-121 Device 7 3.4 Library Functions 9 ics121deviceopen Open an ICS-121 board 9 ics121deviceclose(ics121) Close an ICS-121 board 9 ics121devicereset(ics121) Reset board 9 ics121gainset(ics121) Set gain for One Channel 9 ics121rangegainset(ics121) Set gain on range of channels 11 E10540 REV.A i

1 INTRODUCTION The ICS-121 is a 32-channel single-width 6U VMEbus analog signal conditioning board. It is designed to be used with the ICS-130 Sigma-Delta Analog-to-Digital Converter board. VxWorks is a high performance real-time operating system with UNIX-compatible networking facilities available from Wind River Systems, Inc. This manual describes a VxWorks device driver that implements a standard I/O model for the ICS-121. With this driver and its associated C language function library, an applications programmer can efficiently configure and operate the ICS-121. To facilitate the learning process, working example code is included. These routines configure and operate the ICS-121 under various configurations. Document Overview There are three sections to this document: Section 1 Section 2 Section 3 This section. The Installation Guide describes how to install an ICS-121 and it's device driver into a VxWorks environment. The Programming Guide describes the ICS-121 library that contains routines to perform each of the major card functions. 1.1 Related Documents This document should be read in conjunction with the following related documents: 1. ICS-121 Operating Manual, Interactive Circuits and Systems Ltd., Document number E10539. 2. VxWorks Programmer's Guide, Version 5.1, Wind River Systems Inc., December 1993, Document Number DOC-100000-0002. 3. VxWorks Reference Manual, Version 5.1, Wind River Systems Inc., December 1993, Document Number DOC-100001-0001. E10540 REV.A 1

2 INSTALLATION GUIDE 2.1 Installing the ICS-121 Step 1 - The ICS-121 base address must be selected so as not to conflict with other devices in the target system. The ICS-121 occupies a 256 Byte physical address space. Either A16 or A24 addressing mode may be used to access the board; jumper JP1 on the board determines which mode is active. The base address of the board is selected by means of switches on the board (see Ref. 1). To avoid choosing a physical address which conflicts with memory space already in use, it is recommended that the addresses of any boards already installed be identified. Step 2 - Backplane jumpers for the VMEbus bus grant (BG0 - BG3) signals and the IACKIN/IACKOUT signal may be either in place or removed, as these lines are shorted on the board in order to provide continuity for boards further down the daisy chain. The ICS-121 has no interrupt capability. E10540 REV.A 2

2.2 Installing the ICS-121 Device Driver Software Step 1 - The ICS-121 driver should be placed in the <VxWorks>/src/drv/ics121 directory, where <VxWorks> represents the directory where VxWorks was installed on the host computer. To do this, the installer must login as root (or any other account with Superuser privileges) on the host computer and change the default directory using: $> cd <VxWorks>/src/drv $> mkdir ics121 $> cd ics121 Step 2 - Next, the distribution tape should be inserted into the tape drive and the command: $> tar xv should be used to restore its contents. Once this is done, read the README file, and the file test.c. Step 3 - During normal operation, the driver code in file ics121.c uses the VxWorks function taskdelay() to generate a delay after programming a channel gain value. This is required in order to allow time for the serial data to be clocked to the programmable gain amplifiers. The delay value is determined by the variable ICS121_WRITE_WAIT which is declared near the start of the file. The default delay value is one tick of the processor clock, which is typically 10ms for the Motorola MVME-167 CPU board. The minimum delay required by the ICS-121 is 50µs. The user may need to modify this delay value for the target processor. Step 4 - Rebuild the driver by running 'make'. (The test program assumes operation with a Motorola MVME 167-32A, and an ICS-121 card configured to respond to VME A16/D16 addressing). $> make The ICS-121 driver is now installed and ready for use. E10540 REV.A 3

2.3 Using the ICS-121 Device Driver The test program should be read first. It may need to be customized for your target system. After VxWorks is running correctly on the target processor, you may download and run the test program from the VxWorks Shell as follows: -> ld < <Host_Name>:<VxWorks>/src/drv/ics121/test ------------------ -> test where <Host_Name> represents the Ethernet node name of the VxWorks development station. This example assumes either that the user has a direct serial port connection to the VxWorks target, or else has an Ethernet connection and has performed a remote login to the target. The driver and function library object files may be linked in to any application that uses functions of the driver, in the same way that other functions are included. The test program first calls the ics121drv() and ics121devcreate() functions. If either of these calls returns an error, a message will be printed to the console device and the program will exit. If the latter of these two functions returns an error, it usually means that the board address or jumper JP1 setting are not compatible with the base address and address mode given in the call to ics121devcreate(). Alternatively, the target processor VME mapping hardware may not be correctly programmed. The user must make sure that this is done correctly in all application programs. The test program includes code necessary to configure a Motorola MVME-166, MVME-167 or MVME- 187; however, this code will not be applicable to other computer models. Once the icsdrv() and ics121devcreate() functions have returned without error, a menu is printed on the console. The user may choose to reset the board, to set the gain of a single channel, to set the gains of a range of channels, or to exit the program. E10540 REV.A 4

3 PROGRAMMING GUIDE 3.1 Driver Initialization Functions This section describes the driver initialization functions. NAME ics121drv Initialize ICS-121 Driver SYNOPSIS STATUS ics121drv(void); Initializes the ICS-121driver code for VxWorks. This function must be called before any other ICS-121functions are invoked. If multiple ICS-121boards are installed in the current system, this function need only be called once. RETURNS OK If successful, or if the driver was already initialized, ERROR If VxWorks was unable to initialize the driver. NAME ics121devcreate() Add ICS-121 board to device list SYNOPSIS STATUS ics121devcreate( char *devicename, /* Device name e.g. /ics121/0" */ int adrmod, /* Address Modifier */ unsigned long vmeaddress /* Base address of board */ ); Adds a named ICS-121 board to the VxWorks device list. The driver name parameter should specify the device type ("/ics121") and a unit number ("/n"), where n = 0 to number of cards - 1. The device type/unit number combination must be unique in the system. This function must be called after ics121drv() and before any other ICS-121 function is invoked for this board. The base address must be a value consistent with the A16 or A24 address mode selected with parameter adrmod. It must also be configured using switch blocks SW1 and SW2 on the board; factory default is 0x008000. E10540 REV.A 5

The choice of A16/A24 addressing selected by the adrmod parameter must also be configured using board jumper JP1; factory default is A16. Legal values for the Address Modifier are as follows. The symbols are defined in VxWorks header file <VxWorks>/h/vme.h: VME_AM_SUP_SHORT_IO VME_AM_USER_SHORT_IO VME_AM_STD_SUP_PGM VME_AM_STD_SUP_DATA VME_AM_STD_USR_PGM VME_AM_STD_USR_DATA Short (A16) Supervisory Access Short (A16) Non-privileged Access Standard (A24) Supervisory Program Access Standard (A24) Supervisory Data Access Standard (A24) Non-Priv. Program Access Standard (A24) Non-Priv. Data Access RETURNS OK If successful, or if the driver was already initialized, ERROR If VxWorks was unable to initialize the driver, with errno set to one of: S_ioLib_NO_DRIVER ICS121_INVALID_BOARD ICS121_DEVICE_ALREADY_CREATED ICS121_HARDWARE_INIT_FAILED ICS121_ADD_DEVICE_FAILED E10540 REV.A 6

3.2 Dynamic Installation of ICS-121 Device Driver at Run Time Before the driver can be used, it must be initialized by calling ics121drv(). This routine should be called exactly once regardless of the number of ICS-121 boards in the system. This must be done before any reads, writes, or calls to ics121devcreate(), e.g.: ics121drv(); The function call ics121devcreate() must be made once for each ICS-121 board in the system, giving a unique name to each board. This must be done before any driver I/O functions are called, e.g.: ics121devcreate( "/ics121/0", VME_AM_SUP_SHORT_IO, 0x8000); This example creates the ICS-121 device called "/ics121/0" which will communicate to the ICS-121 board at the address 0x8000 in VME Short address space. The user must ensure that the processor is configured to generate D16 data cycles. If more than one ICS-121 is installed in the system, the file name could then be "/ics121/n", where (n) ranges from 0 to the number of boards installed less one. 3.3 Opening and Closing the ICS-121 Device After calling the device initialization functions described in section 3.1, the ICS-121 must be opened before any I/O can take place between the user and the ICS-121. This may be done either by using the VxWorks open() function or by using the ics121device Open() function included in the function library described in section 3.4. The open() function takes three parameters: the name of the device to be opened, the flags and the access mode. The name of the device to be opened will be the name given to VxWorks by the function call 'ics121devcreate()'. The flags parameter should be O_RDWR, which allows the user to both read and write the device. Further details of this call are given in Ref. 3 under the iolib library entry. If the ics121deviceopen() call is used to open the device, the only required parameter is the device name. When an ICS-121 is successfully opened, both open() and ics121deviceopen() return an integer (the file descriptor) that is used to refer to the active ICS-121 in all subsequent actions. If an error has occurred, open() returns ERROR, while ics121deviceopen() returns NULL. E10540 REV.A 7

A typical application program would use the following code to create and open the ICS- 121 device attached to "/ics121/0": int ics121; if (ics121drv() == ERROR) { printf(" ics121drv returned error\n"); printf(" errno = 0x%x\n", errnoget() ); return (ERROR); } if (ics121devcreate("/ics121/0", VME_AM_SUP_SHORT_IO, 0x8000 ) == ERROR) { printf(" ics121devcreate returned error \n"); printf(" errno = 0x%x\n", errnoget() ); return (ERROR); } if ( (ics121 = ics121deviceopen("/ics121/0")) == NULL ) { printf(" Error opening /ics121/0 "); exit (errno); } The ics121deviceopen() will fail if the device driver has not been installed, if the ICS-121 is not present, or if the ICS-121 is being used by another process. Once the ICS-121 has been successfully opened, the user can control the card using the library functions described in section 3, or the ioctl() routines. When the application has finished using the device, the close() function should be used to free it up for use by other users or processes: ics121deviceclose(ics121); which should generate no errors. E10540 REV.A 8

3.4 Library Functions This section describes the ICS-121 library functions contained in file "121low.c". NAME ics121deviceopen Open an ICS-121 board SYNOPSIS RETURNS int ics121deviceopen( char *devicename /* Device name e.g. /ics121/0" */ ); Opens the ICS-121 attached to "devicename". File descriptor, or A null pointer if an error occurred. The file descriptor is needed in all subsequent library function calls. NAME ics121deviceclose(ics121) Close an ICS-121 board SYNOPSIS RETURNS STATUS ics121deviceclose( int ics121 /* File descriptor */ ); Closes the device attached to the file descriptor "ics121". OK NAME ics121devicereset(ics121) Reset board SYNOPSIS RETURNS STATUS ics121devicereset( int ics121 /* File descriptor */ ); Resets the ICS-121 to a gain setting of -12dB on all channels. OK NAME ics121gainset(ics121) Set gain for One Channel E10540 REV.A 9

SYNOPSIS STATUS ics121gainset( int ics121, /* File descriptor */ int channel_number, /* Number of channel */ int gain /* Gain value, -12 to +42 db incl. */ ); Sets the specified channel (1-32 inclusive) to the specified gain value (-12dB to +42dB in steps of 6dB). After programming a gain value, a task delay of ICS121_WRITE_WAIT of the CPU clock is made before the function returns (see section 2.2 above). RETURNS OK or ERROR, and errno equal to ICS121_INVALID_CHANNEL_NUMBER if channel number not valid. or ICS121_INVALID_GAIN_VALUE if gain value not valid. E10540 REV.A 10

NAME ics121rangegainset(ics121) Set gain on range of channels SYNOPSIS STATUS ics121rangegainset( int ics121, /* File descriptor */ int first_channel, /* Number of first channel to program */ int last_channel, /* Number of last channel to program */ int gain /* Gain value, -12 to +42 db incl. */ ); Sets all of the specified range of channels (1-32 inclusive) to the specified gain value (-12dB to +42dB in steps of 6dB). After programming a gain value to each channel, a task delay of ICS121_WRITE_WAIT of the CPU clock is made before the next channel is programmed or before the function returns (see section 2.2 above). RETURNS OK or ERROR, and errno equal to ICS121_INVALID_CHANNEL_NUMBER if either first_channel or last_channel not valid. or ICS121_INVALID_GAIN_VALUE if gain value not valid. E10540 REV.A 11