IKON Corporation 2617 Western Ave Seattle, WA 98121 (206) 728-6465 15 September, 1997 ************************************************* * * * Solaris 7/8 compatible * * * * x86 version * * * ************************************************* Driver installation instructions and notes for IKON Corporation's Model 10117 PCI Hardcopy interface. THE x86 VERSION OF THIS DRIVER SUPPORTS ONLY THE 1/2 SIZE 10117 WITH THE PLX 9080 CHIP INSTALLED, WHICH SUPPORTS DMA CHAINING FROM PCI MEMORY. MODELS 10115 AND 10117 WITH THE PLX 9060 CHIP INSTALLED (WHICH CANNOT CHAIN FROM PCI MEMORY) ARE NOT SUPPORTED. Files provided on the distribution diskette include: ihcp loadable PCI hardcopy driver module ihcp.debug loadable PCI hardcopy driver module with debug prints enabled ihcp.conf PCI hardcopy driver configuration file ihcp_driver.c code source module for the Solaris 2.x PCI hardcopy driver ihcp_var.h structure definition file for the PCI hardcopy driver ihcp_reg.h register definition file for the PCI hardcopy driver ihcp_io.h ioctl command definition file for the PCI hardcopy driver - to be #include'd' in the calling program ihcp_driver.make make file for Solaris 2.x PCI hardcopy driver - creates ihcp ihcp_driver.make.debug make file with debug prints enabled - creates ihcp.debug ihcp_driver.lint.ex example lint file from good compilation iktest0.c very simple sample program that calls the hardcopy driver iktest0 iktest executable 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 and ihcp.conf 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, OR IT IS NECESSARY TO LOAD THE ihcp.debug VERSION OF THE DRIVER. 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 and conf file to the driver directory: cp ihcp /usr/kernel/drv cp ihcp.conf /usr/kernel/drv If it is desired to run with driver debugging enabled, copy the debug version of the driver to the driver directory instead of the normal version: cp ihcp.debug /usr/kernel/drv/ihcp Edit the /etc/devlink.tab file to add the ihcp device Add the following line(s) to the file: type=ddi_pseudo;name=pci11d5,115 \M0 type=ddi_pseudo;name=pci11d5,117 \M0 (the white space before \M0 is a tab - the 0 is a zero) It is not necessary to add all of the above lines to devlink.tab, only the line(s) that refer the the board(s) actually being installed. Since the ihcp driver will support both the 10115 and 10117 (at the same time), it is appropriate to add both the '115 and '117 lines, although it is not necessary. Then run add_drv to actually install the driver: add_drv -m '* 0666 bin bin' -i '"pci11d5,115" "pci11d5,117"' ihcp This installs the module ihcp with permissions 0666 owned by bin in group bin. The node(s) created in /dev/ will be ihcp0...ihcpx with one node created per board. The entries in /dev/ will be sybolic links to entries in /devices/pci@1f,2000 or its equivalent on the target machine. The above command will install the driver if either or both 10115 and 10117 boards are present. 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 - 1 Aug, 1996) 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. If a 10115 is removed, and replaced with a 10117, or the reverse, a new ihcpx entry will be created. The kernel remembers what type of board was in a given slot, and does not re-use an instance number unless the board is replaced with another of the same type. If a two slot machine had two 10115 boards installed, the one in slot 0 would be named ihcp0 and the one in slot one would be ihcp1. If the slot 0 board is replaced with a 10117, the 10117 would become ihcp2, and the 10115 would remain ihcp1. NOTES: Residual Byte Counts: It is a unix convention that the read and write routines return a count of the number of bytes actually transferred. Unfortunately, the pci interface chip on the 10115, 6, 7, and 8 does not have a readable dma range counter. Therefore, the hardcopy driver always indicates that all bytes requested in a read or write call were transferred. Unless an error was encountered, this will in fact always be the case. Errors will be indicated by the driver returning -1 after a read or write call. In general, bytes lost in an aborted read or write cannot be re-sent successfully anyway, so the "actual" byte count would serve little purpose. "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 ihcp_io.h are new with this driver(new with the Solaris 1 Sbus driver that is). The PCI hardcopy driver maintains compatibility with the Sbus driver's ioctl() commands, and adds a few new ones that may be useful in a PCI environment, and to take advantage of the new board's capabilities. 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. Note that the xxxx_io.h files for Solaris 2.x are slightly different from the xxxxio.h files provided with the drivers for Solaris 1. The SVR4 (Solaris 2.x) 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.) if it was originally written to talk to the VME hardcopy driver. 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 Driver Default Properties: Several driver defaults may be changed by editing the ihcp.conf file (in /usr/kernel/drv) and reloading the driver. This is far simpler than the old approach of editing and re-making the driver itsself. It is the only way to modify defaults in installations that do not have Sunsoft's unbundled C compiler available. The handshake speed for Centronics and Versatec compatible plotters may be set separately using the ihcp.conf properties cent_speed_def and vers_speed_def, respectively. The available choices for each are 0 through 3, with 0 giving the fastest handshake. Generally speaking, the fastest handshake that gives relaible data transfer should be used. Many Versatec compatible plotters will tolerate speed 0, while most Centronics compatible devices will require speed 1 or slower. The factory defaults are both 1. The boot-time default mode for Versatec compatible devices is selected by the mode_def property. If mode_def is 0, the board and plotter will default to print mode. If mode_def is 1, plot mode will be selected. The factory default is 1 for plot mode. Two software timers are used in the driver. One controls how long the driver waits for a DMA transfer to complete. The other times the wait for device ready ioctl. The defaults for these timers are set by dma_time_def, and rdy_time_def, respectively. The appropriate property should be set equal to the desired timeout value in SECONDS. Some plotters can take a relatively long time to complete a transfer, or a plot, so numbers like 1800 seconds (30 minutes) are not unreasonable. The values as shipped from the factory are 1800 seconds for each timer. The x86 version of this driver uses host-based dma chaining, which forms scatter-gather lists in host memory. sg_list_length controls the size of the scatter-gather list, and therefore the amount of host memory (kernel memory) used for lists, and the maximum size of a dma transfer. Each list entry (one per 4K buffer page plus perhaps two more for alignment) requires 16 bytes of host memory. A 64 link chaining list consumes 1024 bytes of host memory, and allows a maximum of 256K bytes per dma buffer. This property may be adjusted up or down to allow large buffers (if you get a "too many cookies" message from ihcp_strategy) or to reduce usage of kernel memory. Minphys (buffer sizes): The ihcp driver uses the system minphys routine when calling the kernel physio from the 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. If necessary, 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)) ; } Power Management: Ikon's Solaris drivers for Pci products support power management at the system level. The board and supported plotter do not have selectable power levels, but the driver will allow the system to power off any time that the board and driver are not open for use by another process. The state of the attached printer or plotter is not controlled during a system power-down sequence, and the driver cannot guarantee the plotter state when power is restored. The driver state will be the same as that immediately before power-down. The above applies to E-Star type operations, not to normal manual system shut-down.