BRIEF GUIDE FOR INSTALLING IKON HARDCOPY BOARD AND DRIVER IN HP-UX VERSION 11.X PCI MACHINES Applies to Ikon Model 10117 Pci Hardcopy Interface NOTE: This README and the driver files with it replace an earlier version of the 11.x driver which did not function correctly with a 64 bit kernel. 4 November, 1999 IKON Corporation 2617 Western Avenue Seattle, Washington 98121 phone: (206) 728-6465 fax: (206) 728-1633 e-mail: ikoncorp@worldnet.att.net www: http://home.att.net/~ikoncorp Other files provided with this driver: ihcp_driver.c source code module for driver ihcp_reg.h definition file for board's registers ihcp_var.h definition file for driver soft-state structure ihcp_io.h ioctl definition file for driver and calling programs ihcp_mod32.o pre-compiled driver for 32 bit kernels ihcp_mod64.o pre-compiled driver for 64 bit kernels master master file for ihcp driver system system file for ihcp driver space.h space file for driver (declares tunable parameters) ihcp_build script that compiles driver to mod.o ihcp_install script that installs and loads driver (mod.o) and creates device node(s) ihcp_mod32.mk script that compiles driver in 32 bit mode (called by build script) ihcp_mod64.mk script that compiles driver in 64 bit mode (called by build script) ihcp_remove script that removes driver modules and unloads from kernel filtertest.c simple program that adds cr to each unix source line for printing iktest0.c simple sample program that prints test message on ihcp0 wsio_dlkm.h HP system file necessary for driver compilation (see below) wsio_private.h HP system file necessary for driver compilation (see below) This guide includes instructions for installing an IKON Model 10117 and driver in HP workstations with Pci I/O slots and running HPUX 11.x. The 11.x ihcp driver is a dynamically loadable kernel module (DLKM). It may be added to a running system, and used immediately, without the necessity of re-booting the system. INSTALLING: 1) Configure and install the board(s) in the appropriate Pci slot(s). All board configuration is done via software, with the exception of the interface type selection, which is done with an on-board jumper cable. Connect the cable between the I/O pin strip, and either the CENT pin strip (for Centronics compatible devices) or the V-DIFF pin strip (for Versatec, VPI, Xerox ColorgrafX compatible devices). A single driver can support multiple boards. 2) Create a directory /usr/conf/ihcp. It will contain the IKON provided files and the results of compile operations. Copy the IKON files to this directory. 3) If any changes are to be made to the driver source code, make them now. If the driver is to be used unchanged, see PRE-COMPILED DRIVER OBJECTS, below. Compiling the Ikon driver requires the use of HP's ANSI compiler, which may not be available on a given machine. If the ANSI compiler is unavailable, see PRE-COMPILED DRIVER OBJECTS, below. The source modules are: ihcp_reg.h Provides "internal" definitions used by all versions of the driver. ihcp_var.h Defines the soft-state structure used by the driver. ihcp_io.h Provides "external" ioctl command definitions used by all versions of the driver, and by the calling application. Also contains some user- modifiable definitions. space.h declaration of tunable parameters ihcp_driver.c The source code module for the driver. 4) Become super-user. 5) Build the driver (ihcp_build) Type "./ihcp_build" The build script will do the following: Remove any existing copy of mod.o (the driver object). Compile a 32 or 64 bit version of the driver, depending which version of the OS is running. 6) Install the driver (ihcp_install) Type "./ihcp_install" The install script will do the following: Run kminstall -d to remove any old copy of the driver. Run kminstall -a to install the driver components. Run config to add the driver to the running kernel. Remove any existing ihcp device nodes. Create ihcp nodes in the /dev/ directory - one per board named ihcp0, ihcp1,... Add ihcp to /etc/loadmods so the kernel will automatically reload the driver on each re-boot. The driver is immediately available to application programs. it is not necessary to re-boot to use the driver. PRE-COMPILED DRIVER OBJECTS: If the driver is to be used as delivered from Ikon, it is not necessary to re-compile the driver source code. On those host machines with no ANSI compiler available, it will not be possible to compile the driver. Pre-compiled driver objects are included with these driver files. One (ihcp_32.o, is to be used with 32 bit kernels. The other (ihcp_64.o) is for 64 bit kernels. To use a pre-compiled driver object, become super user and copy the appropriate object to mod.o: cp ihcp_64.o mod.o Continue the installation with step 6, above. NOTE: Included on the distribution media is a file called iktest0.c. This sample program demonstrates the calling sequences required to issue ioctls to issue board commands and/or set driver parameters, to write to the device attached to the board, and to read back the board's registers. Compile it to run the test, if desired, but make sure the device number is correct first. DEINSTALLING: If it is desired to remove the ihcp driver and associated modules, as super user type "./ihcp_remove". This will unload the driver from the running kernel, and remove the ihcp files from the dlkm directories. It will also delete the /dev/ihcpx device node(s), and remove ihcp from /etc/loadmods. DRIVER MODIFICATION: Should it prove necessary to modify the driver, the source may be edited prior to running ihcp_install. There should be very few occasions when driver modifications are required, as most parameters subject to change may be modified via the kmtune command, without editing the driver (see below). There is a bug in the kernel dlkm code that may require a driver modification once it is fixed (see below). There may be (is on IKON's machine) a problem with the location and/or existence of system files necessary for compilation of the driver. This has been accomodated in this release of the driver, but other platforms and other releases of the OS may require some driver #include statements to be modified. DLKM LOAD BUG: The current version of the OS (11.0) has a bug in the dlkm code. For some reason, when the driver is loaded into a running kernel (ihcp_install), the driver's unload code is called after the board is attached. This causes the driver to partially unload, and leaves things in a confused state. The current cure for this behavior is a 'hack' that causes the driver to ignore the first (bogus) unload, and honor any later requests to unload - usually caused by a manual invocation of kminstall -d. Unfortunately, when the system loads the driver on re-boot (at some later time), there is no 1st bogus unload request. A manual unload request will be ignored, and flagged with the error, "module in use". A second unload request will succeed. Once the kernel code is fixed, there should be no bogus unload request at any time. It may be convenient to modify the driver to respond to any unload request. This may be done by editing ihcp_driver.c and finding the line: ihcp_real_unload = 0; and changing it to: ihcp_real_unload = 1; This particular problem is unlikely to cause any difficulty in normal operation (no manual load/unload), and the user may choose to simply ignore the issue. TUNABLE PARAMETERS: With loadable drivers comes the option to change some operating parameters of the driver without editing the source code. Use of this feature requires manual loading of the driver. The tunable parameters are: ihcp_order_def default byte order, 0 = low byte first, 1 = high byte first ihcp_vers_speed_def default Versatec speed, 0 = fastest, 3 = slowest ihcp_cent_speed_def default Centronics speed, 0 = fastest, 3 = slowest ihcp_mode_def default Verstatec mode, 1 = plot, 0 = print ihcp_dma_time_def default dma timeout in seconds ihcp_rdy_time_def default ready wait timeout in seconds ihcp_sg_list_lenght default scatter/gather list length ihcp_debug 0 = normal driver operation, 1 = enable debug prints to log To set any of these parameters, (from /usr/conf/ihcp, as super user): rm mod.o (if present) make -f ihcp_mod32.mk (or ihcp_mod64.mk) kminstall -d ihcp (if previously loaded) kminstall -a ihcp (install driver files) kmtune default_parm=value (i.e. kmtune ihcp_debug=1 - repeat for other parms) config -M ihcp -u (load driver into kernel) add ihcp to /etc/loadmods (driver will be re-loaded on each re-boot) It is also necessary to make the device node(s) in the /dev/ directory. This can get a little messy, so it is probably easier to install a vanilla driver first - which creates the device node(s) - reload with the new parameters, as above. If it is really necessary to create the node(s) by hand, refer to the ihcp_install script for an example. MANUAL INSTALL/REMOVAL: The driver may be manually loaded and unloaded. This is useful if the user needs to modify any tunable parameters. It is also useful when dealing with the bogus unload bug (see above). See the description above for driver loading instructions. To unload the driver manually: kminstall -d ihcp (unloads driver, deletes /etc/loadmods entry) rm /dev/ihcp* (removes device node(s)) If the driver unload attempt fails with an 'in use' or 'busy' error, it may be due to the unload bug. If so, a second attempt to unload should succeed. If a second kminstall -d fails, it may be that user modifications to the source code have rendered the driver "un-unloadable". In this case, modify the driver to correct the error, re-make, and use: kminstall -u ihcp this will cause the corrected driver to be loaded at the next re-boot. 32/64 BIT OPERATION: The driver may be compiled for 32 or 64 bit operation. The driver mode must match that of the kernel into which it will be installed. ihcp_install will check the KERNEL_BITS variable to determine which compile mode to use. If the driver is compiled manually, use ihcp_mod32.mk or ihcp_mod64.mk for the makefile, as appropriate. NOTE: The driver expects the argument used in ioctl() calls to be a pointer to a 32 bit data type, regardless of the driver/kernel operating mode. If an application has defined its ioctl arg as a pointer to type long, which will be 64 bits wide on a 64 bit machine, it will have to be modified, and re-compiled. MISSING SYSTEM FILE: On the development system available to IKON (a Merlin), a system file was missing, and one was in the wrong directory. It is unknown whether this problem is consistent on all HP platforms. We have taken the liberty of including the missing file with the driver files. This is a little bold, but necessary for now. If the types and macros defined in those files change, it will be necessary to modify the driver source to point at the version (hopefully) included by HP in future versions of the OS. The file in question is wsio_dlkm. The driver currently inlcudes it in the ihcp directory with the statement: #include "./wsio_dlkm.h" In the future, it may be necessary to use: #include "../wsio_dlkm.h" or: #include "../wsio/wsio_dlkm.h" Further, on IKON's machine, the file eeprom.h was in the wrong directory for other system include files to find it. It was copied from /usr/include/sys to /usr/conf/wsio to get things to work. We apologize for the mess, but IKON doesn't have much control over this! Hopefully, this will all be sorted out in the next release of HPUX. Alternativly, if the driver source is not to be modified, use the pre-compiled driver object appropriate to kernel (32 or 64 bits) and do not compile the driver at all.