IKON Corporation 2617 Western Ave Seattle, WA 98121 (206) 728-6465 1 November, 1994 Driver installation instructions and notes for IKON Corporation's Sbus interface products, including the 10103 DR11-W emulator, and the 10104, 10105, and 10106 Hardcopy interface boards. The examples below refer to ihcpxxx software and utilities for the 10104, 5, and 6. Use the idrxxx software and utilities for 10103 applications. for example: make -f idr.mak, idr.INSTALL, etc. To compile driver: make -f ihcp.mak After running make, check the ihcp.lint file for warnings and errors. This file is set up so that lint is run twice. The first run does not attempt to resolve kernel references and warning messages appear above the dotted line in the ihcp.lint file. Those from the second run appear below the line and should not include unresolveds. Warnings about conversion from long, and varaible # of args in printf calls are normal. It is not necessary to make the driver unless it has been modified. If it is to be used as shipped, simply install it. Install and "un-install" require superuser privileges. Either log in as root, or execute su command. The following operations should be executed from the directory containing the files provided on the IKON diskette. To install loadable driver: ihcp.INSTALL Produces these files at /dev /dev/ihcp0 /dev/ihcp.MKDEV* /dev/ihcp.LOAD* /dev/ihcp.UNLOAD* /dev/ihcp.RMDEV* /dev/ihcp.NIHCPS /dev/ihcp.INSTALL -> /home/ihcp.INSTALL* /dev/ihcp.o -> /home/ihcp.o /dev/ihcp.ID /dev/ihcp.AUTOLOAD (if autoload option was selected at INSTALL time) NOTE: the device node created is ihcp0, the identify routine will report the name IKON,ihcp0 which is the name used in the board's fcode prom to identify the board to the driver. To "un-install" loadable driver: first use modstat to determine the appropriate id#, then: modunload -id id# -exec /dev/ihcp.RMDEV Once a driver is loaded, its status can be checked using modstat: modstat Id Type Loadaddr Size B-major C-major Sysnum Mod Name 5 Drv ff0f0000 4000 60. ihcp NOTES: "Rewinding" the Driver: A quirk of the unix file system calls treats the ihcp 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 ihcp driver. This call should be made often enough that the hidden counter never goes negative. IOCTL parameters: The majority of the ioctl() commands defined in ihcpio.h are new with this driver. Also defined are a set of commands intended to be compatible with SUN's driver for IKON's model 10088 VMEbus board. This should allow existing printer/plotter applications to run with little or no modification. The DR11-W driver's ioctl() commands are all new with this driver. See the xxxxio.h files for each driver for ioctl command descriptions. Device Names: The application code calling the Hardcopy driver may expect a different node name than that created by the install script. (vp0, lp0, etc.) It may be necessary to establish a symbolic link between the /dev/... entry that the application expects to see, and the /dev/ihcp0 (or 1, or 2) that the ihcp.INSTALL script creates. DR11 Driver IOCTL Calls: See the file called 103notes for info on driver calls and defaults. 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. This test program may be used in both Solaris 1.x and 2.x applications. It 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. At the end of each pass, it outputs an asterisk "*". In the event of an error, it prints a brief message and exits. DR11 Sample Link Program: The idrlink.c program is a simple example of a DR11 to DR11 interprocessor link using the 10103 and driver. SUN OS Bugs in 4.1.1 on SPARC2 and IPX: THERE IS A BUG IN THE 4.1.1 VERSION OF UNIX FOR THE SPARCSTATION 2 THAT PREVENTS IKON'S (AND OTHER) Sbus CARDS FROM BEING MAPPED INTO THE SYSTEM CORRECTLY. SUN's Sbus suport group has provided a patched UNIX to IKON and other 3rd party developers, for release to our customers. See the README.sun file included on this diskette. This bug is also present in the IPX kernel. Changing DMA Timeout Parameter: Prior to ~1 Feb 1992, the default timeout value for both the DR11 and Hardcopy drivers was 30 seconds. (too short for most plotters) As of 1 Feb, the factory default for the DMA watchdog timer (software timer) is 30 seconds for the DR11 driver and 30 MINUTES for the Hardcopy driver. This may be too short for some applications - particularly when using the Hardcopy driver with large multi-pass color plotters that take a long time to make a plot. To change the default timeout value: Locate the #define DMA_TIME_DEF 1800 line in the ihcpio.h file. Change the 1800 to the desired value in seconds. Re-compile the driver: make -f ihcp.mak Unload the old driver using the id # provided by the modstat command: modunload -id id# -exec /dev/ihcp.RMDEV Load the new driver: ihcp.INSTALL 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 xxxio.h file. These may need to be modified if the timeout value requested in an ioctl call falls outside of the limits. In the original version of the driver(s), long timeouts were a problem. If the driver was sleeping - waiting for DMA done, or some other condition - a kill signal would not wake it up, and the operator would have to wait for the full timeout time before regaining control of the process using the driver. See below for further info. Changing Other Default Parameters: It may be useful in some applications to run the drivers with default options different from those set by IKON. This is especailly true in the case of a hardcopy board that is driven via cat or lpr. In these cases, there is no opportunity to call the driver with new configuration requirements, such as selecting plot mode (as opposed to print, which is the normal default), or using one of the higher speed handshake timings ( the default is the slowest handhsake timing available). Application code that calls the driver directly can configure the board and driver at run time, but cat and lpr (unless filters are used), must live with the compile time defaults, as only the write() portion of the driver is used. One of the default parameters is discussed above, in "Changing DMA Timeout Parameter". The other defaults of interest in hardcopy applications are the handshake timing (SPEED_DEF), and the print/plot mode (MODE_DEF). These "defines" are found in the ihcpio.h file. THESE DEFAULTS ARE GLOBAL, AND APPLY TO ALL BOARDS SERVED BY A PARTICULAR DRIVER. IF IT IS NECESSARY TO USE DIFFERENT DEFAULTS FOR SPECIFIC BOARDS, IT WILL BE NECESSARY TO MODIFY THE ihcp.c FILE ON A BOARD-BY-BOARD BASIS. There are three default speed choices available: IHCP_SPEED0 through IHCP_SPEED3. IHCP_SPEED3 is the fastest, and gives a maximum handshake speed of approximately 1.5Mbytes/second. IHCP_SPEED0 gives a maximum rate of approximately 330Kbytes/second. IHCP_SPEED0 is the factory default. Note that the 10106 (Centronics) board supports all four speeds, but the 10104 and 10105 (Versatec) boards only actually support speed2 and speed3. If the board is a 10104 or 10105, speed0 = speed2, and speed1 = speed3. If the board is a 10104 or 10105, there are several default print/plot modes available. The factory default is normal print mode (IHCP_NORM_PRINT). Other available modes are IHCP_PLOT_MODE, and IHCP_SPP_MODE (simultaneous print/plot mode). These may be selected individually, or simultaneously. IHCP_SPP_MODE is not likely to be used as a default, but IHCP_PLOT_MODE is a reasonable default if the attached plotter operates in plot mode only. These "defines" are used in software dated 14 April, 1992 or later. Prior to that time, these defaults were set directly in the ihpc.c code. In either case, the default parameters are set in the ihcp_attach() routine. There are several hardware defaults used in the 10103 driver. All are contained in the idrio.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. New "Breakable" Drivers: As of ~1 Feb 1992, both the DR11 and Hardcopy drivers have been rewritten to allow sleeps to be awakened by signals. This allows the timeout values to be set long if necessary, and still allows the process calling the driver to be "killed" immediately by a signal. In order to accomplish this a few other changes to the Hardcopy driver were necessary. The close routine no longer waits for plotter ready before closing, and the board and plotter are no longer reset in the open and close routines. At this time, the Hardcopy timeout default was set to 30 MINUTES. (21 Feb 1992) The above changes to the sleep logic awoke a bug left over from the original sample driver from sun. See "bugs" below. New 10103 Features: Early versions of the 10103 were shipped with a DR11 control array labelled FPGA2. This array incorporated a 20 bit range counter, giving a maximum DR11 block length of 2Mbytes. As of ~1 Feb 1992, FPGA3 will be used. This part has a 24 bit range counter, for 32Mbyte blocks, and adds a multicycle error detector. This error logic detects when the device asks for another transfer while the board is still busy with the previous transfer. It is useful when connected to a data generating device that makes constant transfer requests without waiting for an ack from the 10103. The MCER bit will set if the device overruns the 10103's fifo. Driver Bugs: The original versions of both the Hardcopy and DR11 drivers had similar bugs. There are ioctl calls that cause the driver to test for a specific condition: READY true or ATTENTION recieved for the DR11 driver, and fifo empty or fifo less than half full for the Hardcopy driver. The code would test for the condition and return if it was true. If the condition was false, the code would enable the condition to interrupt, and sleep until an interrupt or timeout. The code left a small window between enabling the interrput and sleeping where the interrupt could occur. The wakeup would be issued in the interrupt code with nothing sleeping, and would be lost. The sleep would then time out. This would most likely not cause a problem, but could potentially confuse the calling process. The fix is to bracket the interrupt enable and sleep with START_CRITICAL(unit_no) and END_CRITICAL(unit_no) to raise the processor priority higher than the board's interrupt level. Sleep lowers the priority, and allows the interrupt to occur. This problem is corrected in both drivers as of ~1 FEB 1992. The changes incorporated in the 1 February 1992 release revealed a sleeping bug in the original sample driver from sun. The internal interrupt priority saved in each board's unit structure was placed in a u_char. Sadly, the internal priority was shifted left so that it could be plugged directly into the cpu's registers, and this shift pushed the bits out the left end of the u_char. The result was that the START_CRITICAL routine didn't really raise the priority, and short dma blocks could cause an interrupt before the ihcp or idr strategy routine called sleep. The wakeup would be lost, and strategy would sleep until timeout. The fix changes the interrupt_pri element of the unit structure to a u_int. This change is incorporated as of 21 February 1992. The few copies of the driver diskettes which were released between 1 Feb, and 21 Feb, 1992 should be discarded or returned to IKON. Unhappily, the 4 or 5 diskettes labelled 21 Feb, 1992 also contained a bug in the ihcp interrupt code. If the board was installed with another board on the same interrupt level, and the ihcp driver was installed first, there was a chance that the interrupt polling code would get stuck in a loop from which one could not escape with L1-A !!! The fix is to do a flush_buffer within the interrupt code to make sure that the interrupt_pending bit is off before leaving the interrupt service routine. Diskettes labelled 1 and 21 Feb should be erased!!!!! This bug is fixed as of 27 February 1992. All versions of the 10103 driver, idr.c, prior to 15 September, 1994 will fail to function correctly on SUN machines that have write buffering enabled, such as the SPARC 5 and 20. Earlier machines had write buffering, but apparently it was not enabled, or operated in a way that did not cause problems. The "ikon" portion of the logic on the 10103 requires approximately 300ns following a register write to complete its internal write operation. Another write within this time could potentially corrupt the previous write. Earlier versions of the idr driver used DELAY(1) statements between writes to guarantee this time. Unfortunately, on a machine with write buffering, the delay occurs between writes TO the buffer, not writes FROM the buffer to the board. If bus activity caused more than one write to be queued in the buffer, the writes would end up being issued back-to-back to the 10103, causing intermittent problems such as dma timeouts and data corruption. The fix is to replace the DELAY(1) calls with calls to an internal delay routine that forces the write buffer to flush by reading two "ikon" registers on the board that is being written. The two reads also guarantee sufficient time for the internal operation to complete. The idr driver dated 15 September, 1994 also corrected a potential problem with the interrupt code. It turns out that, unlike the sample code, the interrupt routine must poll the ERROR_PENDING bit in the csr, along with the INTERRUPT_PENDING bit. A dma error, such as an attempt to dma to/from non-accessible memory, would cause an interrupt via the ERROR_PENDING bit, without causing the INTERRUPT_PENDING bit to set. This meant that the interrupt routine did not recognize this type of interrupt, and indicated to the kernel that the interrupt was not serviced. This caused the kernel's interrupt polling code to loop indefinitely! The fix does not prevent whatever hardware or operation error might cause a dma error, but prevents the machine from locking when this occurs. The 1 November, 1994 mod fixed a bug in the IDRIO_RDY_WAIT ioctl.