README.ihcp.64 Readme file for Tahoma Technology PCI hardcopy driver for Models 10115 & 10117 SPARC Version Solaris 7 and later Tahoma Technology (formerly Ikon Corporation) 107 2nd Avenue North Seattle, WA, USA 98109 206.728.6465 http://www.tahomatech.com tahoma@tahomatech.com 11 NOvember, 1999 27 May, 2004 changed IKON to Tahoma Technology Driver installation instructions and notes for Thahoma Technolgy (formerly IKON Corporation) PCI Hardcopy interface products, including the Models 10115 and 10117. These files and instructions apply to Solaris 7 and later. This version of the driver will not compile correctly on earlier versions of Solaris. The files included on this diskette may be used to install (and create if necessary) either 32 or 64 bit versions of the driver. Files provided on the distribution diskette include: ihcp.32 loadable 32 bit PCI hardcopy driver module ihcp.debug.32 loadable 32 bit PCI hardcopy driver module with debug prints enabled ihcp.64 loadable 64 bit PCI hardcopy driver module ihcp.debug.64 loadable 64 bit 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.32 make file for 32 bit Solaris 7 driver - creates ihcp.32 ihcp_driver.make.debug.32 make file for 32 bit Solaris 7 driver with debug enabled creates ihcp.debug.32 ihcp_driver.make.64 make file for 64 bit Solaris 7 PCI hardcopy driver ihcp_driver.make.debug.64 make file for 64 bit Solaris 7 driver with debug enabled creates ihcp.debug.64 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 ikonex.c program to test & exercise plotter, driver, and board can output data files and strings to plotter, set modes, and read status - cmd line and interactive modes ikonex.h include file for building ikonex ikonex ikonex executable After a successful pkgadd, these files will be found in /opt/IKONihcp (assuming that the default base directory - /opt - has been used). ihcp.32 and ihcp.conf will also be copied to /usr/kernel/drv (with ihcp.32 renamed ihcp), and ihcp.64 will be copied to /usr/kernel/drv/sparcv9 (with ihcp.64 renamed ihcp), /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 the 32 bit driver: /usr/ccs/bin/make -f ihcp_driver.make.32 To compile the 64 bit driver: /usr/ccs/bin/make -f ihcp_driver.make.64 The compiler called in the makefile is the SparcWorks compiler - version 5.0 or later. 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. With the versions of cc and lint available at this time, there will be many warnings - none of which indicates a driver problem. The result of a successful make is the loadable module: ihcp.32 or ihcp.64. 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 Tahoma Tech diskette. To install loadable driver: Copy the driver module and conf file to the driver directory: 32 bit version: cp ihcp.32 /usr/kernel/drv/ihcp cp ihcp.conf /usr/kernel/drv 64 bit version: cp ihcp.64 /usr/kernel/drv/sparcv9/ihcp 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: 32 bit version: cp ihcp.debug.32 /usr/kernel/drv/ihcp 64 bit version: cp ihcp.debug.64 /usr/kernel/drv/sparcv9/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 (Tahoma Tech hardcopy 2005.05.27.1415) 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. 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 Tahoma Tech'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. NOTE: The ihcp driver requires that the values pointed to by the arg parameter in the ioctl call be 32 bit variables!! (the only exception is the array used by the DATA_OUT ioctl whicl must be an array of type char or uint8_t). If an application using the ihcp driver currently defines the *arg type as long or u_long, it will fail if re-compiled under 64 bit Solaris, which makes type long a 64 bit value! Any such application must be edited prior to re-compilation, to make all *arg values 32 bits -- as in uint32_t or type int, which is still 32 bits wide. Existing 32 bit applications should continue to run correctly if not re-compiled. 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. iktest0 will write set print mode (if the board is strapped for vpi), print "hello world" 10 times, issue a form feed, and print the contents of the board's registers to the console. The default device opened is /dev/ihcp0 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 Ikonex: ikonex is a command-line or interactive program that can be used to test and exercise the plotter, board, and driver. It is based on the Ikondma program written by Bill Simpson at Interface Consultants. ikonex can output pre-formatted print and/or plot files (if available), manipulate plotter modes, send pulsed commands, set interface parameters such as handshake speed, and retrieve interface and plotter status. Data bytes and strings may also be sent directly from the keyboard. ikonex is self-documenting. Type ./ikonex for a list of commands. 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 ignore_minphys parameter can be used to ignore the system's buffer size limits. (see below). if ignore_minphys is set to one, the system minphys() routine will not be called by ihcp_minphys. Minphys (buffer sizes): The ihcp driver uses the its lolcal minphys routine when calling the kernel physio from the write routine. Minphys uses IHCP_MAXPHYS, and the system's minphys() routine to determine 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 either limit, 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 for some reason it is necessary to use continuous larger buffers, the ignore_minphys parameter can force the driver to ignore the system minphys limit (which may be conservative). Ignoring minphys does not create additional mapping resources -- if the system's limit is exceeded, physio will return an error. Ignoring minphys may also impact overall system performance. IHCP_MAXPHYS must not be modified! 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.