Ikon MS-DOS TSR Driver Model IVBD1013

Version 1.20 June 12, 1996
Reprinted June 12, 1996

Copyright 1992,1993 Interface Consultants, Inc., Houston, TX
Interface Consultants, Inc.  3375 Westpark Drive #143, Houston, TX 77005-4262


1. Introduction

The Interface Consultants Model IVBD1013 Ikon MS-DOS device driver is a TSR (terminate and stay resident) program that intercepts the BIOS printer interrupt (17 hex), and extends it to support Versatec plot mode DMA and commands compatible with the Versatec M110A implementation.

The device driver supports the following Ikon Hardcopy PC/AT bus interface boards:
Ikon 10092
Ikon 10097
Ikon 10111

The actual device driver is 'ikontsr'. The 'ikoninit' program initializes the device driver.

A test program 'ikontest' is provided (with C source code) that produces both print and plot mode data.

A file output program 'ikondma' is provided that allows DOS files to be output to a plotter in print or plot mode, or a printer using high speed DMA.

A board status display program 'ikoninfo' displays information about whether the 'ikontsr' is loaded, and if it has been initialized with 'ikoninit'. If initialized, the current driver and board register information is displayed.

Data transfer speeds of up to 800K bytes per second can be expected in a 'real' application.

The device driver supports the operation of only one Ikon board at any one time. The driver can be re-initialized with ikoninit without reloading ikontsr to select other Ikon boards at different I/O base addresses.

The device driver passes output to printer ports other than the one installed onto the original printer driver (Int 17h handler).

Disclaimer: Marks copyright Interface Consultants, Ikon, or Xerox.

2. Installation of the software

Copy all the files on the distribution diskette into a working directory, e.g.:
C:\>mkdir drivers
C:\>copy a:\*.* drivers

Set the PATH to the installation directory, or alternatively, use the full path with the program name, e.g.:

The TSR is installed by typing 'ikontsr' at the DOS prompt. The driver is activated by typing 'ikoninit' with the proper parameters at the DOS prompt. A test program ('ikontest') is provided (with C source) that produces both print and plot mode data.

See the following sections for configuration details.

3. Configuring the Ikon board

Before installing the Ikon board in your computer it must be configured. See the Ikon manual for details on DIP switch and ribbon cable settings.

The Ikon board uses a block of eight (8) I/O addresses, one DMA channel, and one interrupt. Determine what other resources are used in you computer, and select an unused DMA channel, interrupt level, and base I/O address.

The device driver uses DMA and interrupts to achieve high performance. The Ikon board must be strapped to use a free DMA channel and a free interrupt. We have found that most computers have DMA channel 7 and interrupt 15 free. We use base address 120 hex (0x120) as our default, since it is not used by most adapters, and the 300 hex I/O region is often crowded and used by adapters that do not document what address they use.

The Ikon board ribbon cable must be set to the proper position. Almost all newer Versatec interfaces use V-DIFF (Versatec differential or long lines). Older plotters may use V-TTL. If you are using Centronics (or sometimes called IBM parallel), set the ribbon cable to CENT. The ribbon cable end plugged into I/O never gets changed. Make sure you are not off by one row or one pin when changing the cable.

After setting the DIP switches and ribbon cable, turn you computer off, and install the Ikon board in an empty slot, and cable the board to your printer or plotter. Do not put your cover back on yet. Turn the machine and printer/plotter on, and use the test plot switches on the Ikon board to verify the ribbon cable setting, cabling to the plotter, and plotter operation. See the Ikon manual for use of the test plot switches.

Next, install and initialize the driver, and run ikontest or ikondma. See the following sections for details.

After ikontest produces a good plot, or ikondma produces good print, turn your computer off, and put the cover back on.

4. Ikontsr - loading the device driver

Typing 'ikontsr' at the DOS prompt loads the TSR into memory. The ikontsr must be initialized by 'ikoninit' before becoming active. The normal first time installation sequence is:

1. Copy the distribution disk to a working directory.
2. Set the DIP switches and ribbon cable on the Ikon board.
3. Install and test the Ikon board and cabling with the test plot switches.
4. Load the driver into memory:
5. Initialize the driver :
C:\>ikoninit -p3 -a0x120
(Where -p3 is lpt3: and the board is set for base i/o address 120 hex.)
6. Run a test output:
If you are driving a plotter use:
(Prints 'hello' and plots black and white bars)
If you are driving a printer use:
C:\>ikondma -f readme.doc
(Copies text file readme.doc to the printer)

The output from running ikontsr is:
Ikon MS-DOS TSR driver version 1.01 Jan-21-1993
Copyright Interface Consultants 1992,1993

Mapmem shows that ikontsr version 1.01 takes 7680 bytes of memory.

5. Ikontsr programming interface

The driver uses the bios printer interrupt vector (0x17) and extends the functions (only functions 0, 1, and 2 are BIOS supported) to provide plot mode dma and remote commands to a Versatec interfaced printer/plotter.

This implementation is compatible with the Versatec M110 'outasm' routines, and replaces the 'vrsprn' TSR. Function AH=11 is compatible with 'vprinter.com' TSR version 3.0B.

The user program sets up the required register and executes INT 17h to invoke the ikontsr driver.

AH = 0 Print the character in AL. Status returned in AH.
AH = 1 Initialize printer port. Status returned in AH.
AH = 2 Read printer status. Status returned in AH.
AH = 3 Start DMA transfer in plot mode. (Note: this call waits for the previous dma transfer to complete)
AL = DMA page register
BX = buffer starting address
CX = word count to be transferred
AH = 4 Wait for the previous DMA transfer to complete.
AH = 5 Remote Reset Command to plotter.
AH = 6 Remote Clear Command to plotter.
AH = 7 Remote Form Feed Command to plotter.
AH = 8 Remote EOT Command to plotter.
AH = 9 Remote Line Terminate Command to plotter.
AH = 10 Start DMA transfer in plot mode (same as AH=3). Note: byte swapping is handled by dip switch on Ikon board. AH = 11 Start DMA transfer in print mode. (same as AH=3, but print mode)
AH = 0x99 Extended function, ds:dx point to ext_fcn structure.

DX = Printer number (0=LPT1,1=LPT2, or 2=lpt3) Note: this driver does not require the base address to be one of the default PC lpt addresses, but is setup by 'ikoninit'.

AH = Status (normal good status is 0xd0, 0x02 = not initialized)
Bit 7 = 1 Printer not busy (ready)
Bit 6 = 1 Acknowledge (always 1)
Bit 5 = 1 Out of paper (1 when not online)
Bit 4 = 1 Printer Selected (ready)
Bit 3 = I/O Error (always 0)
Bit 2 = Reserved (always 0)
Bit 1 = Reserved (1 if not initialized by ikoninit or BIOS)
Bit 0 = 1 Timeout error (always 0)

Extended Functions: ref: fcn AH=0x99 (99 hex, 153 decimal)

The definition of the ikontsr extended function structure in C (ref: fcn AH=0x99 (99 hex, 153 decimal)) used in the extended functions is:

struct ext_fcn {
int port; /* not used */
int fcn; /* extended fcn */
int parm1; /* data to/from extended function */
int parm2; /* data to/from extended function */
int parm3; /* data to/from extended function */
int parm4; /* data to/from extended function */
int parm5; /* data to/from extended function */
int parm6; /* data to/from extended function */
int parm7; /* data to/from extended function */
int parm8; /* data to/from extended function */
int parm9; /* data to/from extended function */
int parm10; /* data to/from extended function */
} x_fcn;

Get Driver Info:
Calling arguments:
fcn = 2
Returned arguments:
parm1 = lpt_num (e.g. 2 = lpt3:)
parm2 = ioaddr
parm3 = dma_mode
parm4 = major revision level
parm5 = minor revision level

Long Reset Command:
Calling arguments:
fcn = 3
parm1 = number of 18.2Hz ticks for reset, or 0xffff = assert reset and return, or 0x0000 = release reset and return.
Returned arguments:

Wait Command:
Calling arguments:
fcn = 4
parm1 = number of 18.2Hz ticks to wait.
Returned arguments:

6. Ikoninit - initializing the device driver

The 'ikoninit' program initializes the ikontsr and tells it the base address to which the Ikon board is set, and which printer port to capture. Typing 'ikoninit' with no parameters prints the following synopsis:

Ikon MS-DOS driver initialization - version 1.01 Jan-21-1993
Copyright Interface Consultants 1992,1993
Error -a /addr_port/ is a required parameter
Error -p /lpt_port_number/ is a required parameter
Usage: ikoninit -p<> -a<> [-d<> ]
-a /addr_port/ e.g. -a0x120 or -a288 is port 120 hex
-p /lpt_port_number/ e.g. -p3 is lpt3:
-d /dma_mode/ (this is an optional parameter)
-dSINGLE is single cycle dma mode
-dDEMAND is demand transfer dma mode (default)
-dBLOCK is block transfer dma mode (do not use)
-dCASCADE is cascade dma mode (do not use)

Note: at initialization, once the base port address is known, the hardware interrupt level and dma channel are read from the Ikon board dip switches. The byte swap feature is controlled by dip switch, not software. The dma mode controls are optional, but can improve dma transfer speed. Interrupt 15 and DMA channel 7 are free on most machines.

7. Ikontest - test plot and programming example

The ikontest program is provided with C source code as an example of how to write a user program that interfaces to the ikontsr device driver.

The following is the screen output from the ikontest program:

Ikon MS-DOS driver test program - version 1.01 Jan-21-1993
Copyright Interface Consultants 1992,1993
ikontsr set to lpt3:
block = 0 cnt=1000
block = 1 cnt=2000
block = 58 cnt=59000
block = 59 cnt=60000

The plotter output for ikontest is the word 'hello' output in print mode, followed by black and white stripes of plot mode data (4 nibs on, 4 nibs off). Thermal plotters will plot in yellow and white.

To advance the plot out of the plotter, do a manual form feed, or output a form feed command using ikondma as follows:
C:\>ikondma -cVTFF

8. Ikondma - file dma output program

The 'ikondma' program allows DOS files to be output to a plotter or printer in print or plot mode using high speed DMA. Ikondma is double buffered, and executes command line functions in a left to right order as entered. Ikondma is full featured, in that it can perform any plotter function that a user program can issue.

Typing 'ikondma' with no parameters prints the following synopsis:

Ikon MS-DOS driver DMA output program - version 1.01 Jan-21-1993
Copyright Interface Consultants 1992,1993
Usage: ikondma [-d<>] [-m<>] [-r<>] [-w<>] [-f<>] [-c<>] [-v]
-d /dma_size in Kb/ (optional - default=16 max=128)
-m /mode/ mode for transfer, PRINT(default) or PLOT
-r /reset time/ # of 18.2Hz ticks to reset printer/plotter 0xffff=assert, 0=release
-w /wait time/ # of 18.2Hz ticks to wait
-f /file name/ data file to dma to port
-c /command/ Remote command to plotter, can be:
VRST - Versatec Remote Reset
VCLR - Versatec Remote Clear
VTFF - Versatec Remote Form Feed
VEOT - Versatec End or Terminate
VRLT - Versatec Remote Line Terminate
-v verbose mode

Note: args are executed left to right as found, multiple files in different modes can be sent in a single command. e.g.
ikondma -d32 -mPRINT -ffile1.prn -mPLOT -ffile2.plt
sends file1.prn in print mode, and then file2.plt in plot mode

Full Versatec 'greensheet' output can be implemented with ikondma if preamble and rewind commands are put into files that are output in print mode, and plot data padded to the correct bytes per scan in color separate files is output in plot mode.

9. Ikoninfo - driver and board information

Ikoninfo is a program that prints information about the ikontsr driver and the current state of the Ikon board.

Typing 'ikoninfo' without the ikontsr loaded prints the following:

Ikon MS-DOS driver information - version 1.01 Jan-21-1993
Copyright Interface Consultants 1992,1993 *********************************************************** Ikon driver info:
Ikon tsr driver NOT loaded: run ikontsr and ikoninit

Typing 'ikoninfo' without the ikontsr initialized prints the following:

Ikon MS-DOS driver information - version 1.01 Jan-21-1993
Copyright Interface Consultants 1992,1993 *********************************************************** Ikon driver info:
Ikon driver NOT initialized: run ikoninit

Typing 'ikoninfo' with the ikontsr loaded and initialized prints the following:

Ikon MS-DOS driver information - version 1.01 Jan-21-1993
Copyright Interface Consultants 1992,1993 *********************************************************** Ikon driver info:
I/O Address = 120 (hex), 288 (decimal)
IVBD1013 Version = 1.01 *********************************************************** Ikon board info:
Latched function reg: 120 = 00 (hex)
TENB OFF = disable internal test mode
TVRY OFF = de-assert test ready
LRST OFF = latched device reset off
DMON OFF = dma disable
DSTR OFF = data streaming mode off (TEK)
IENB OFF = interrupt disable
VSPI OFF = not versatec spp
VPLT OFF = versatec print mode *********************************************************** Interface Status reg: 121 = cf (hex)
DIRY ON = device and interface ready
DVRY ON = device ready
IFLG OFF = no interrupt flag
WORD OFF = dma 16bit
SWAP ON = no byte swap
TSEL ON = test pattern 1
FPLT ON = force plot switch off
DTST ON = device test mode off *********************************************************** Device Status reg: 123 = b2 (hex)
Versatec differential interface selected
VRDY ON = versatec ready asserted
CBDR OFF = centronics busy NOT asserted
PMTY OFF = versatec or centronic paper OK
ONLN ON = device online and selected
CFNI OFF = centronics FAULT NOT asserted *********************************************************** Interface Strapping reg: 124 = ff (hex)
DMA channel = 7
Interrupt = 15 (decimal)
Terminator Status = 1 (pull-up or bridge installed) ***********************************************************

10. Programming Notes

The ikontsr is designed for easy double buffered DMA implementation. Buffer- one is filled by your program, and then your program calls int 17h with a DMA function. The ikontsr driver starts DMA from buffer-one, and returns immediately to your program. Your program now fills buffer-two, and calls int 17h again with a DMA function. The ikontsr waits for DMA buffer-one to complete, then starts DMA buffer-two, and returns to your program. Your program can now fill buffer- one with new data. This allows overlapped filling of the next data buffer with the DMA output of the previous DMA buffer for maximum performance.

Single buffered DMA can be implemented if required. After your program fills the buffer and calls int 17h with a DMA function, it must call int 17h with the 'wait for DMA complete' (function AH=4) before putting new data in the buffer. The 'wait for DMA complete' function waits in the ikontsr until the buffer is output.

All Int 17h functions automatically wait for DMA complete when appropriate to ensure proper double buffered operation.

Ikontest.c is a C source code example of how to interface to the ikontsr device driver from C.

Interrupts to other LPT ports are passes on to the original printer driver.

The PC AT 16-bit DMA hardware cannot DMA data that crosses 128K byte boundaries. The IKONTSR driver automatically breaks data buffers that cross a 128K boundary into two DMA operations that do not cross the boundary. The maximum data size that the hardware can support is 128K bytes. For maximum performance, arrange for your data buffers to not cross 128K byte boundaries.

In the 'real' mode (the mode in which MS-DOS runs) the CPU can generate addresses only within the lower megabyte of physical memory (1M byte plus 64K bytes minus 16 bytes to be exact, and depending on the state of the A20MASK bit). The PC AT DMA hardware can only DMA from the lower 16 megabytes of physical memory. The parameters to Int 17h support the full 16M byte DMA addressability range.

11. Application notes

If you are using a memory manager (Qemm or 386max), make sure to set the DMA=xxx parameter to the largest DMA block size used. Not setting this parameter can cause the computer to 'lock up' during DMA.

If you are having problems with the data being wrong (black streak bands on the plot), decrease the size of the DMA buffer. It is possible for 386 memory managers to map memory such that the DMA buffer 'disappears' from physical memory.

Mapmem, mark, and release are public domain utilities that help with TSR management. See the tsr.doc on the distribution disk. Use 'mark' and 'release' if you want to be able to remove ikontsr from memory.

The TSR utilities are used during initial debug or if you want to be able to remove ikontsr without re-booting the computer. In a production system, it is expected that mapmem, mark, and release will not be used.

The IVFD1014 plotting program is available to output greensheet raster files from Freedom of Press to Versatec compatible plotters using the IVBD1013 driver.

12. Demo Versions

Ikontsr and Ikoninit are available as demos.

The demos have all of the capabilities of the licensed versions except in one area. The tsr will plot out the first 10 blocks of dma buffers at normal speed. After that, the plotter will pause 5 seconds between every dma buffer output.

If you would like to purchase this product, please feel free to contact us here at Interface Consultants for more information.

13. Revision History

1.00 12/12/92
- Initial full release

1.01 01/21/93
- ikontsr
- fix data error on chaining across 128K byte boundaries
- add long reset extended function
- add wait extended function - add MCLR board reset on initialize
- ikoninit
- change default DMA mode to DEMAND
- ikondma
- add long reset function -rxxxx
- add wait function -wxxxx

1.20 06/12/96
- ikontsr
- ikoninit
- updated for release on Internet as a demo.
- ikoninfo
- updated to verify version (demo or licensed)