IKON Corporation 2617 Western Ave Seattle, WA 98121 (206) 728-6461 14 October, 1997 ************************************************* * * * Solaris 2.x compatible * * * ************************************************* Driver installation instructions and notes for IKON Corporation's Model 10104, 10105, and 10106 Hardcopy interface boards. Files provided on the distribution diskette include: ihcp loadable hardcopy driver module (made on IPC) ihcp_driver.c code source module for the Solaris 2.x hardcopy driver ihcp_var.h structure definition file for the hardcopy driver ihcp_reg.h register definition file for the hardcopy driver ihcp_io.h ioctl command definition file for the hardcopy driver - to be #include'd' in the calling program ihcp_driver.make make file for Solaris 2.x hardcopy driver ihcp_driver.lint.ex example lint file from good compilation iktest0.c very simple sample program that calls the hardcopy driver filtertest.c simple filter that adds carriage returns to text files for printing (on laserjet for example) filtertest filtertest executable After a successful pkgadd, these files will be found in /opt/IKONihcp (assuming that the default base directory - /opt - has been used). ihcp will also have been copied to /usr/kernel/drv, /etc/devlink.tab will be modified, and add_drv will have been run. IT SHOULD NOT BE NECESSARY TO PERFORM ANY OF THE FOLLWING MANUAL INSTALLATION PROCEDURES UNLESS THE DRIVER SOURCE HAS BEEN MODIFIED BY THE USER. To compile driver: make -f ihcp_driver.make The make available on IKON's machine is in /usr/ccs/bin, so: /usr/ccs/bin/make -f ihcp_driver.make The compiler called in the makefile is the SparcWorks compiler. After running make, check the ihcp_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: ihcp. 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 ihcp /usr/kernel/drv Edit the /etc/devlink.tab file to add the ihcp device. Add the following line to the file: type=ddi_pseudo;name=IKON,ihcp \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,ihcp ihcp This installs the module ihcp with permissions 0666 owned by bin in group bin. The node(s) created in /dev/ will be ihcp0..ihcp9 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 ihcp 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 ihcp (IKON hardcopy - 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 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(new with the Solaris 1 driver that is). Also defined are a set of commands intended to be compatible with SUN's and Versatec's drivers 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 xxxx_io.h files for each 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. 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, or ...) that add_drv creates. Hardcopy Sample Program: iktest0.c is a (very) simple sample program that calls the hardcopy driver. It indicates in general how to use the ioctl call, and how writes are done. Filtertest: This tiny program is a sample filter that can be used when printing through the hardcopy driver. It will scan its input, looking for new line characters, and will add a carriage return when it finds a new line. This allows printing unix text files to printers that require carriage returns - HP laserjet is one example. To print directly to the hardcopy device, on might do something like: pr | ./filtertest > /dev/ihcp0 Changing DMA Timeout Parameter: Prior to ~1 Feb 1992, the default timeout value for the Hardcopy driver was 30 seconds. (too short for most plotters) As of 1 Feb, 1992, and for all Solaris 2.0 compatible versions of the drivers, the factory default for the DMA watchdog timer (software timer) is 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 ihcp_io.h file. Change the 1800 to the desired value in seconds. Re-compile the driver: make -f ihcp_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. 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 driver 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 ihcp_io.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_driver.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_SPEED1 is the factory default as of the Solaris 2.0 driver. This gives a maximum handshake speed of approximately 700Kbytes/second for the 10106. 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. Minphys (buffer sizes): The ihcp 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 is usually not a problem for hardcopy devices, which expect an continuous stream of data. 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. xxxx_minphys sample: #define IHCP_MAXPHYS some appropriate buffer size static void ihcp_minphys(struct buf *bp) { bp->b_bcount = (min(bp->b_bcount,IHCP_MAXPHYS)) ; }