SVN-specific manuals | Main | Usage | MB6 Patches
Official manuals | README | Video Instructions

[Home]
Parallel Port Passthrough and Virtual Printer Patch
Contents

1. Introduction to parallel port emulation
2. Assigning a device to a LPT port
3. Parallel Port Passthrough
4. Virtual Printer
5. File redirection

| Introduction to parallel port emulation Three features are provided by this patch:

1. A virtual color dot-matrix printer. It parses ESC/P text and graphics data (not laser printer data) from the program and draws an image thereof. The image can be printed to PNG, BMP or Postscript files. It can also be forwarded to a Windows printer, however black-and-white only so far. Options for page size and resolution are availible
2. Redirection to a file or host LPTx interface. The data is written, after optional simple translation, to a file This mode has three sub-modes. The most simple one writes the data to files in DOSBox' capture directory. The second option is to append the data of several subsequent printouts to a specified file. Third, data can be forwarded to a parallel port device such as LPT1 on the host.
3. Parallel port passthrough. This feature is currently implemented for Windows and Linux. Before the file redirection was implemented, this was useful for accessing parallel printers. Now it is still useful for software protection dongles and LPT I/O hardware, as long as it is not very timing critical.

| Emulated LPT ports The parallel ports provided by DOSBox are controlled through the [parallel] section in the configuration file. Each port can be assigned one of the three modes, however there can only be one virtual printer.

- parallelx=disabled
Disables this port.
- parallelx=reallpt
Parallel Port Passthrough - additional parameters can be added on the line.
- parallelx=file
File redirection - additional parameters can be added on the line.
- parallelx=printer
Virtual Printer - parameters are set in the [printer] section.

If you activate the disney sound device, LPT1 is overridden. So if you want to use the passthrough or virtual printer leave disney disabled.
Emulated interfaces for all types of devices:

- I/O at 378h/278h/3BCh
- BIOS INT17
- DOS INT21
- DOS file (PRN/LPTx) access
- DOS handle #4 access

| Parallel Port Passthrough Requirements:

- Windows (Win9x, NT, Win2000, XP32, Vista32) or Linux as host operating system
- For Windows, a ECP/EPP or SPP register compatible parallel port is required

Limitations:

- Interrupt from parallel port is not supported
- Parallel Port to USB adapters are not supported
- Some modern parallel ports may not be compatible with older hardware
- Timing issues with emulation can give improper results or cause failure with certain applications
- Does not work nonstandard parallel ports (Windows)
- Unlikely to work with USB-Parallel adapter cables

Windows
Set parallel1=reallpt in dosbox.conf. If you use a parallel port different from the standard LPT1 built on mainboards, you need to specify the port's base address. This can be looked up in the Windows device manager. Usually LPT2 is at 278.
Example: parallel1=reallpt realbase:cc00
Entering a wrong I/O port address can mess up your system, so doublecheck what you write there.
PCI parallel port cards may use a different addressing scheme for the ECP control ports. DOSBox uses the ECP registers to switch the port into bidirectional SPP (normal parallel port) mode. To make this work on the PCI card you can specify the ECP address through the ecpbase keyword. Consult your device manager and/or the datasheet of the PCI port for the actual value.
Example: parallel1=reallpt realbase:cc00 ecpbase:cc08

Linux
The parallel port device is passed. Security attributes may have to be changed.
Example: parallel1=reallpt realport:/dev/parport0

Debug Log Thi build has parallel port debugging enabled which is useful for reverse-engineering old communication protocols. The actions a program performs on the parallel port are recorded in a text or binary files located in the capture subdirectory. The different types of actions can be filtered in the following categories:

- dbgdata - write a info line (timing, value) when the parallel port's data port is written
- dbgput - write a line when data is written to LPT1/PRN
- dbgregs - write a line when any registers of the parallel port are accessed
- dbgputplain - only write bytes that are written to LPT1/PRN as file
- dbgdataplain - only write bytes that are written to the data register
- dbgall - all debugging parameters except plain

The desired categories are added to the parallelx configuration parameter, i.e.:
parallel1 reallpt dbgput dbgregs
parallel1 reallpt dbgputplain
Virtual Printer The Virtual Printer emulates a color dot-matrix printer that follows the ESC/P2 printing standard. Features:

- Many of the ESC/P and ESC/P2 instructions supported
- Graphics printing for 24-pin and 48-pin modes supported, up to 360dpi
- Color output, use "Generic ESC/P 24pin wide" printer on Windows 3.11 or "Epson SQ 860" on Win95
- Data can be output as Windows bitmap, PNG file, Postscript file, or sent to a Windows
- Some older non-conflicting IBM control codes are supported

Limitations:

- Windows printer output in black & white only
- Not all ESC/P commands are supported, like custom fonts
- The default font (roman.ttf) is ugly and characters are misplaced, you may want to replace it with one of the others
- Due to overexact graphics emulation 360dpi printing from Windows (guest) graphics rastering might not look as expected
- When set to use a Windows printer, the printer dialog will only show up once at start
- Country code setup and other configuration buttons found on a printer are not availible, this may be overcome by sending special ESC/P commands to the printer before printing

The virtual printer adds the following parameters in the dosbox.conf under [printer]:

- printer
  true enables the virtual printer. Handy if you'd like to use it.
- dpi
  Resolution of printer (default 360). 180 is another one that makes sence.
- width
  Width of paper in 1/10 inch (default 85 = 8.5')
- height
  Height of paper in 1/10 inch (default 110 = 11.0' US Letter)
  For other paper formats, see Paper size on Wikipedia
- printoutput
  Specifies how to save the output of the printer.
  - png
    Saves to a PNG file (default)
  - ps
    Saves to a Postscript file
  - bmp
    Creates BMP images (very huge files, not recommend)
  - printer
    Send to an actual printer (Print dialog will appear)
- multipage
  Adds all pages to one Postscript file or printer job until CTRL-F2 is pressed.
- docpath
  The path where the output files are stored. Default is the DOSBox program directory.
- timeout
  (in milliseconds) if nonzero: the time the page will be ejected automatically after when no more data arrives at the printer. Useful when the DOS program does not do that itself.

Convincing the printer to produce output
There are several conditions under which the virtual printer will output a page.

- No more text fits on the current page
- The DOS program sends a formfeed character or toggles autofeed on the parallel port
- The user presses CTRL+F2
- If the timeout value is set and no more data has arrived in the timespan

File redirection The modes of operation are chosen by adding parameters like this:

- dev:
Example: parallel1=file dev:LPT1
This forwards the data to the host printer on LPT1.
- append:
Example: parallel1=file append:text.txt
The printouts will be added to 'text.txt'.
- None of the two above:
Example: parallel1=file
A capture file [appname]###.prt will be created in the DOSBox capture directory for every print-out.

Further optional parameters:

- timeout
Example: parallel1=file dev:LPT1 timeout:1000
How long to gather data before writing it.
As soon as data is sent to the port by the emulated application, the file/device is opened and the timeout starts counting. Every time data is sent the timeout is reset. If eventually the application will stop sending data, the timeout will be reached and the file closed. The value is passed in milliseconds.
- addFF
Example: parallel1=file dev:LPT1 addFF
Adds a formfeed when the timeout is reached before closing the file. This is useful when printing plain text to laser printers 'page printers' to persuade them to print the page immediately.
- addLF
Example: parallel1=file dev:LPT1 addLF
Adds a linefeed character at the end of a text line if the application doesn't.
- cp:###
Example: parallel1=file dev:LPT1 cp:437
Performs character translation to ANSI code. The number of the code page the emulated application is using is appended and can be one of the following: 437,737,775,850,852,855,857,860,861,863,864,865,866.
No guarantee of them all being correct ;).

SVN-specific manuals | Main | Usage | MB6 Patches
Official manuals | README | Video Instructions