FD-DISPLAY.SYS/PRINTER.SYS: codepage management for console and printer ====================================================================== =========================================================================== FD-DISPLAY.SYS/PRINTER.SYS: implements codepage management (generic IOCTL) for the console and printer devices Copyright (C) 2002-2006 by Aitor SANTAMARIA_MERINO aitor.sm@gmail.com Version : 0.13b Last edit: 2006-08-06 (ASM) This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. =========================================================================== The following hard-ware specific code is included: EGA/VGA adapter version 0.13b 2002-2006 under the GNU-GPL license by Aitor SANTAMARIA_MERINO aitor.sm@gmail.com and Ilya V. VASILYEV hscool@netclub.ru CGA adapter (GRAFTABL) version 0.13 2002-2006 under the GNU-GPL license =========================================================================== 0.- INTRODUCTION ================ DISPLAY.SYS and PRINTER.SYS are device drivers that supply existing drivers with codepage replacement capabilities (through the IOCTL interface). Both routines have hardware type dependant routines to do the actual job, as well as (mainly) two other routines, one to SELECT the wanted codepage, interfacing with whichever other DOS programs is due, and interfacing between the fixed (firmware) and the configurable (software) codepages, and a second routine, PREPARE, to manage several buffers with information about different codepages. DISPLAY also hooks the multiplexer (2Fh) interrupt vector to interface with the rest of DOS. However, they share much of the code, so that the sources supplied here are supposed to be valid for both. Communication between the user and the device driver to change codepage is made through IOCTL calls, where a generic IOCTL call informs the device (e.g. CON) that a codepage change is starting, and that the contents of a CPI (Codepage Information) file is going to be sent through the IOCTL WRITE line. Usual DOS kernel device drivers for which codepage selection has a meaning, such as CON or PRN, do not implement the response of these calls. The mission of DISPLAY.SYS and PRINTER.SYS is to implement these functions without disturbing with the rest device driver calls. Both drivers are linked to hardware-specific routines, that may belong to third party developers. Typical hardware for DISPLAY includes different graphic adapters, and for PRINTER different printer adapters. 0.1.- Who should use the software You use this software if you want to add codepage support to your console or printer in FreeDOS (or any other DOS). 0.2.- Compatibility At this stage of development (pre-1.0), DISPLAY and PRINTER do not interface through the usual device driver interface, but through the multiplexer. There is no PRINTER driver, due to: - PRINTER does not have multiplexer interface - there are no printer-specific routines submitted to the FreeDOS project The codepage information should come as a CPI file (older RAW files are deprecated and unsupported). Currently supported hardware by DISPLAY: CGA adapters (i.e. GRAFTABL) EGA adapters VGA adapters LCD adapters Please see the hardware specific documentation for more information. DISPLAY/PRINTER 0.13 CORE SOURCE is supplied under the GNU-LGPL license. This version is linked to EGA/VGA and CGA code, which are both distributed under the GNU-GPL version, thus the whole package comes under the GNU-GPL. If you wish to create new hardware specific routines, please read the accompaining documentation. Please do make sure not to link version- incompatible sources. I.e. you cannot compile the EGA/VGA driver with a third party closed-source hardware specific code. 0.3.- Limitations and incompatibilities A maximum of 8 codepages can be prepared at a time (depending on the available memory, up to 64KB, which gives a practical maximum of 5). It is incompatible with older versions of DR-KEYB, with MS-MODE and with unspecific versions of FreeDOS MODE (please always check the documentation of MODE to see the versions of DISPLAY for which MODE works). 0.4.- Version This is version 0.13b of FreeDOS DISPLAY. (version 0.13b is a bug-fixed version of version 0.13. This document will refer to version 0.13 to mean version 0.13b) 0.5.- Copyright Version 0.13 of this program is distributed under the GNU General Public License version 2.0. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. The license applies regardless if it includes runtime libraries or packing forms (online compression) which are not open source. 0.6.- Installation DISPLAY requires a single executable. In this version, it is distributed as an EXE file (DISPLAY.EXE), (later versions from 1.00 onwards may be distributed as a SYS device driver). To operate with DISPLAY you may need FreeDOS MODE and CPI files. Look for them in the FreeDOS repository. Place your DISPLAY.EXE commandline in AUTOEXEC.BAT if you want DISPLAY to load automatically when you boot up. 0.7.- Known bugs and reporting bugs There are no known bugs. If you find a bug, please make sure that the bug affects DISPLAY.EXE and not MODE or the CPI files that you are using. If the problem is MODE or in the CPI files, then you would need to contact the respective developers. If you want to report bugs, please fill a bug report on the FreeDOS Bugzilla: http://www.freedos.org/bugs/bugzilla/ Alternatively, write an email to Aitor SANTAMARIA MERINO aitor.sm@gmail.com 0.8.- File history FD-DISPLAY has grown as a large number of files around the original code by Ilya V. Vasilyev (now contained in EGAR.ASM and VIDEOINT.ASM). The rest of the files have been written anew by Aitor Santamarķa Merino. 0.06: int2Fh interface, MODE interface 0.07: PREPARE and SELECT use independent buffers 0.08: commandline parsing 0.09: communicate with others (KEYB, PRINT, ARABIC/HEBREW, GRAFTABL) modularity (PRINTER.SYS is now possible with the same sources) error codes reported 0.10: parse CPI files 0.11: support for CGA GRAFTABL locking EXE file (instead of COM) prepared buffers loaded into XMS (if available) 0.12: Ability to prepare more than 1 codepage at a time (Generic IOCTL pseudo-call) 0.13: Core code separated from the hardware specific code (and change on license) Heavy source re-structure New commandline parsing Fix the crash when-no-XMS bug 0.9.- Acknowledgements I am sincerely very grateful to a large number of people that have helped me. Henrique Peron for his help and bug reports. Ilya V. Vasilyev for the original DISPLAY, and presently for the EGA/VGA specific code. 1.- DISPLAY and PRINTER features ================================ At this stage of development, nor DISPLAY neither PRINTER are device drivers that communicate through device driver calls. They are loadable TSRs, and in the case of DISPLAY, it communicates with the rest of the world through a slightly enlarged muliplexer interrupt. PRINTER has no binary, being one of the reasons that it has no way to interface with programs outside. It is intended that they will work as they should in version 1.0. For a list of other limitations of current version, see the sections below. As mentioned above, there is no PRINTER executable file. There are only three diferences on DISPLAY.SYS and PRINTER.SYS: - DISPLAY.SYS has a multiplexer interface (PRINTER doesn't) - Both have their font signature in their files (1 DISPLAY, 2 PRINTER) - DISPLAY interfaces with KEYB, PRINTER with PRINT) The codepage preparation is usually made by the DOS MODE command, whereas the selection is directly made by the kernel-loadable NLSFUNC component, or improperly, by the DOS MODE command. When preparing the codepages, MODE sends to DISPLAY/PRINTER the information of codepages included into CPI files. The FreeDOS repository should have the latest MODE needed and sets of CPI files. Also notice that Eric Auer has implemented into MODE the capability of using self-compressed CPX files. As the file is compressed into a CPI before it is sent to DISPLAY, there's no problem with using these CPX files in what concerns DISPLAY or PRINTER. DISPLAY 0.12 EGA/VGA specific routine is able to admit DR-FONTs. Note however that you would need a DR-FONT-aware MODE. 1.1.- Commandline syntax Be sure that no other DISPLAY program (identified though int2Fh, MUX=ADh, fn=00) has been previously loaded. The commandline is of the form: DISPLAY devname[:]=(hwname,[hwcps],buffers) [/C] [/V] [/NOHI] DISPLAY devname[:]=(hwname,[hwcps],(buffers,param)) [/C] [/V] [/NOHI] devname Name of the device for which generic IOCTL is implemented (DUMMY at the moment, usually CON) hwname Name of the hardware adapter (CGA, EGA,...). See NewHW.txt for a list hwcps List of hardware codepages. Either a single number (for a single codepage) or a list (n1,n2,...) for several hardware codepages. (For more than one codepage, you'll need third party drivers, such as ARABIC.COM or HEBREW.COM) buffers A single number representing the number of buffers that you want to allocate, or a pair (buffers,subfonts) with the number of buffers and the number of subfonts wanted param This optional parameter is passed to the hardware-specific routine. See the hardware-specific routine documentation for more information /C ExClusive: will not load if there is another DISPLAY loaded /NOHI Forbid to use XMS to store the prepare buffers /V Verbose: prints extended information Example: DISPLAY CON=(VGA,437,2) specifies to use DISPLAY for the CON device, for an VGA adapter type and 2 buffers for prepared codepages. To interface with DISPLAY, use FreeDOS MODE. Please make sure that the version of MODE that you are using matches the DISPLAY versioning. DISPLAY does not offer the possibility to unload once loaded. 1.2.- Exit codes and causes of errors DISPLAY produces no exitcodes, but provides a set of errors through the int2Fh/AD03h function for each function. You should check it after each unsuccessful operation. Error code Operation Meaning ------------------------------------------------------------------------------ 1 All Unknown function 26 Select Codepage was not prepared 26 Query No dodepage was already selected 27 Select KEYB failed to change codepage 27 Query Device error 27 Prepare The codepage was not found in file 29 Select Device error 29 Prepare Device error OR XMS error 31 Prepare Source file damaged OR XMS error 31 End Prepare No Start prepare found ------------------------------------------------------------------------------ 1.3.- DISPLAY features The following is a brief list of features of DISPLAY: * Codepage management support for a standard character device (generic IOCTL). * Codepage buffer preparation to XMS * MS compatibility in commandline and API (but incompatible with MS MODE) * Modular and easily extensible. Currently supports CGA, EGA, VGA * Last but not least, it is open source software under the GNU-GPL 2.0, which is written in NASM assembler 1.4.- Compiling the driver To compile DISPLAY, get the latest NASM release and compile it in its binary form. The result is a COM file. The program is finally packed using the open source UPX packer, and turned into an EXE file using COM2EXE. Apply UPX first, and COM2EXE next. UPX: http://upx.sourceforge.net/ COM2EXE: get Arakdy Belousov's CuteMOUSE Respect to the structure of the program, there is a main assembler where the rest of the files are included. For the filelist, please check the DISPLAY.ASM documentation. Finally, the program TEST by Ilya V. Vasilyev is included. It helps testing DISPLAY in the different screen modes. 1.5.- Interactions DISPLAY/PRINTER 0.10 interact with other parts of DOS. Namely: - KEYB (DISPLAY.SYS): KEYB is asked to replace codepage when it is due DISPLAY.SYS fails if KEYB fails - PRINT (PRINTER.SYS): PRINTER.SYS checks wether PRINT is already in use PRINTER.SYS fails if PRINT is printing - GRAFTABL (DISPLAY.SYS): GRAFTABL has priority over DISPLAY.SYS when setting fonts - ARABIC/HEBREW (DISPLAY.SYS): DISPLAY.SYS calls these to manage more than one hardware codepages 1.6.- Future wishes In a nearby future, I'll be considering these tasks: (1) Turn the files into proper device drivers (expect by 1.00) Here I show a list of wishes that I'd leave for other contributors: - load CPI files in several chunks (as MS-DISPLAY does) - configure more than one device at a time. E.g.: DEVICE=PRINTER.SYS LPT1=... LPT2=... - (DISPLAY.SYS) communicate with ANSI.SYS via IOCTL calls - (PRINTER.SYS) enable the Privileged Lock Codepage Switching feature 2.- Brief review about using FreeDOS MODE for codepages ======================================================= (please read the documentation accompaining FreeDOS MODE) MODE CON CODEPAGE gets status of DISPLAY.SYS and prepared/selected codepages MODE CON CODEPAGE PREPARE=((nnn) file.CPI) prepares codepage nnn from file.CPI into the first buffer MODE CON CODEPAGE PREPARE=(([mmm,]...nnn) file.CPI) prepares the given codepages in the given buffers from file.CPI MODE CON CODEPAGE SELECT=nnn makes codepage nnn be active for DISPLAY.SYS (and thus makes your screen to display those characters) Codepage nnn must have been prepared beforehand For the moment, this is the only way to select the DISPLAY codepage. However, note that in the future, you are not supposed to use MODE for doing that. You'd rather do it by loading NLSFUNC and calling the internal command CHCP, like CHCP 850 Finally, if for some reason, your codepage was messed, you can always recover it with the REFRESH command: MODE CON CODEPAGE REFRESH Please always read the fast help of MODECON program to know more about it. <<>>