IKON Corporation 2617 Western Ave Seattle, WA 98121 (206) 728-6465 14 October, 1997 ************************************************* * * * Solaris 2.x compatible * * * ************************************************* Driver installation instructions and notes for IKON Corporation's Model 10103 Sbus DR11-W emulator. Files provided on the distribution diskette include: idr loadable DR11-W driver module (made on IPC) idr_driver.c code source module for the Solaris 2.x DR11-W driver idr_var.h structure definition file for the DR11-W driver idr_reg.h register definition file for the DR11-W driver idr_io.h ioctl command definition file for the DR11-W driver - to be #include'd' in the calling program idr_driver.make make file for Solaris 2.x DR11-W driver idr_driver.lint.ex example lint file from good compilation link.master.c very simple interprocessor link program (master end of link) that calls the DR11-W driver link.master link.master executable link.slave.c simple interprocessor link program (slave end of link) link.slave link.slave executable link.master.manual.c version of link master that demonstrates use of MANUAL mode link.master.manual link.master.manual executable idr.loop.test.c loop-back test source for PCI DR11-W board idr.loop.test loop-back test executable 103notes information on using the DR11-W driver After a successful pkgadd, these files will be found in /opt/IKONidr (assuming that the default base directory - /opt - has been used). idr and idr.conf will also have been copied to /usr/kernel/drv, /etc/devlink.tab will be modified, and add_drv will have been run. NOTE: It should not be necessary to perform any of the following manual installation procedures unless the driver source has been modified by the customer. To compile driver: make -f idr_driver.make The make available on IKON's machine is in /usr/ccs/bin, so: /usr/ccs/bin/make -f idr_driver.make The compiler called in the makefile is the SparcWorks compiler. After running make, check the idr_driver.lint file for warnings and errors. The file ihcp_driver.lint.ex contains a lint file from a successful compilation. The result of a successful make is the loadable module: idr. NOTE: It is not necessary to make the driver unless it has been modified. Install and "un-install" require superuser privileges. Either log in as root, or execute the su command. The following operations should be executed from the directory containing the files provided on the IKON diskette. To install loadable driver: Copy the driver module to the driver directory: cp idr /usr/kernel/drv Edit the /etc/devlink.tab file to add the ihcp and/or idr device. Add the following line(s) to the file: type=ddi_pseudo;name=IKON,idr \M0 (the white space before \M0 is a tab - the 0 is a zero) Then run add_drv to actually install the driver: add_drv -m '* 0666 bin bin' -i IKON,idr idr This installs the module idr with permissions 0666 owned by bin in group bin. The node(s) created in /dev/ will be idr0..idr9 with one node created per board. The entries in /dev/ will be sybolic links to entries in /devices/sbus@1,f8000000 or its equivalent on the target machine. To "un-install" loadable driver: rem_drv idr Use the modinfo command to verify that the driver is installed and attached. The modinfo line for the ihcp driver will look something like: 105 ff3e9000 3a84 84 1 idr (IKON DR11 - 20 Oct, 1992) The driver will show up in modinfo only when it is actually loaded into the kernel. add_drv forces the driver to load, and any call of the driver`s entry points will cause an autoload. The kernel may unload the driver if it has been idle for some (unknown!) length of time. When a card is to be removed or moved to another slot, rem_drv should be run before (re)moving the board. If a second card is added, it seems to be necessary to rem_drv & add_drv to establish the correct device mapping. NOTES: "Rewinding" the Driver: A quirk of the unix file system calls treat the idr driver as if it were a tape or disk controller. The system stuff that handles the write calls adds up the total of all bytes transferred to a given device. When this 32 bit counter goes negative, the write will not be permitted, and the call will return an error value. The solution to this problem is to have the routine that calls the ihcp driver do an lseek(filedescriptor, (off_t)0, 0) call to "rewind" the idr driver. This call should be made often enough that the hidden counter never goes negative. IOCTL parameters: See the xxxx_io.h files for the driver for ioctl command descriptions. Note that the xxxx_io.h files for Solaris 2.0 are slightly different from the xxxxio.h files provided with the drivers for Solaris 1. The SVR4 (Solaris 2.0) ioctl macros require that the ASCII portion of the macro argument be quoted - the Solaris 1 macros required that the ASCII argument not be quoted. The old and new ....io.h files will generate the same ioctl commands, but are not interchangeable. Use the new xxxx_io.h files when compiling on a Solaris 2 machine. DR11 Driver IOCTL Calls: See the file called 103notes for info on driver calls and defaults. DR11 Sample Link Programs: The link.master and link.slave programs implement a simple example of a DR11 to DR11 interprocessor link using the 10103 and driver. These programs are compatible with the equivalent program for the Pci board and driver, and with IKON's in house test link software for IKON's other DR11 emulator products. They may be used for testing, or as examples of the link protocol, and how to communicate with the driver. Also included on this diskette is a version of the link master program - link.master.manual - that runs in manual mode. This is a simple demonstration of how to use multiple read and write calls per DR11 block. This technique is useful in continuous data collection applications. A link connection is accomplished by cross-connecting J1 and J2 between two DR11 emulators (or the real thing!). J1 connects to J2, and J2 to J1. This can be done using short transition cables from the DR11s to a pair of ground-plane ribbon cables, or in the case of IKON pci or Sbus boards, by using a single round, jacketed, shielded link cable. DR11 Loop-back Test Program The idr.loop.test program can be used to perform a repeating loop-back test of the 10103. It requires that an appropriate loop-back cable be installed. This cable accomplishes a pin-for-pin connection between the two sides of the 80-pin high-density connector, or between J1 and J2 of the transition cable assembly. The test program first tests the three software timeout functions of the driver, and then loops indefinitely on several tests of the features of the board and driver. Every 100 passes, it prints a message and continues. In the event of an error, it prints a brief message and exits. Changing DMA Timeout Parameter: The factory default for the DMA watchdog timer (software timer) is 30 seconds for the DR11 driver. This may be too short for some applications. To change the default timeout value: Locate the #define DMA_TIME_DEF 30 line in the idr_io.h file. Change the 1800 to the desired value in seconds. Re-compile the driver: make -f idr_driver.make Unload the old driver, copy the new driver to /usr/kernel/drv, and load the new driver. The timeout values may also be changed by using ioctl() calls to the driver at run time. Note that the driver checks for min and max values as defined in the xxxx_io.h file. These may need to be modified if the timeout value requested in an ioctl call falls outside of the limits. Changing Other Default Parameters: It may be useful in some applications to run the drivers with default options different from those set by IKON. There are several hardware defaults used in the 10103 driver. All are contained in the idr_io.h file. These "defines" are: MODE_REG_DEF, LATCH_REG_DEF, READ_FCN_DEF, READ_PULSE_DEF, WRITE_FCN_DEF, and WRITE_PULSE_DEF Proper understanding of the use of these defaults requires specific knowlege of the application, and a careful reading of the the 10103 manual. Typically, application code will call the idr driver directly, and the defaults will be set at run time. Minphys (buffer sizes): The idr driver uses the system minphys routine when calling the kernel physio from their read or write routine. Minphys determines how large a buffer may be passed from physio to the driver's strategy routine. If the read or write call involves a user buffer larger than minphys, physio will break it into pieces, and make miltiple calls to strategy. This can be a problem for DR11 compatible devices, which MAY want to see a well-defined (via GO and/or READY) beginning and end to each block transferred. Multiple strategy calls per buffer may confuse the device. A way around this is to edit the driver source and add a local minphys routine. A sample of a typical minphys routine is shown below. If a MAXPHYS number larger than the system's mapping capability is chosed, ddi_dma_buf_setup will fail. It will be necessary to choose an appropriate MAXPHYS number for the particular target system. Another way to get around this problem is to use the "MANUAL" mode in the DR11 driver. This allows controlling the beginning and ending conditions of the externally visible block transfer directly with ioctl calls, while satisfying the block size requirement with multiple read/write calls or by using a single read/write call with a large buffer and letting physio break it into pieces. In this mode, the strategy routine does not issue a GO pulse with each strategy buffer transferred. See the file 103notes and the driver source for further information. xxxx_minphys sample: #define IDR_MAXPHYS some appropriate buffer size static void idr_minphys(struct buf *bp) { bp->b_bcount = (min(bp->b_bcount,IDR_MAXPHYS)) ; }