FreeDOS DISPLAY and PRINTER v0.10  (26-Nov-2003)
=================================


    Aitor SANTAMARIA_MERINO  (aitorsm@inicia.es)
        2002-2003


    Contributed code and first steps by
        Ilya V. Vasilyev  (hscool@netclub.ru)
            2000


DISPLAY device driver for FreeDOS


     This  program  is  free  software;  you can redis-
     tribute 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.

------

   1.- About DISPLAY and PRINTER
   2.- Hardware supported
   3.- Interactions
   4.- How to use the program
   5.- Using MODECON.EXE
   6.- Known Issues and Limitations
   7.- Future wishes


1.- About DISPLAY and PRINTER
=============================

DISPLAY.SYS and PRINTER.SYS are device drivers that supply existing drivers
with codepage replacement capabilities.

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 balancing 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 some interrupt vectors 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 IN 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.

The difference between both is that DISPLAY will monitor the video adapter
interrupt (10h) to trap mode changes and restablish the codepage when it is
required, and that it communicates with the rest of the world through the DOS
multiplexer interrupt (2Fh), MuX code ADh.

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.

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.

New in this version is the capability of them to admit a very basic and
limited ussage of CPI files where to extract the codepage info from.
Therefore, RAW files are no longer supported, you use CPI files instead. Look
in the FreeDOS repository for CPI file packages. At least there will be one
by Henrique Peron.

Ilya V. Vasilyev is the author of the first DISPLAY-style program, that
appeared inside his CHCP05b package. Ilya's code has place today as:
- the video interrupt manager
- the EGA hardware type selection routines
for which I am deeply grateful.


2.- Hardware supported
======================

DISPLAY.SYS supports the following hardware types (for graphic adapters):

   EGA
   VGA
   LCD

PRINTER.SYS does not have an executable file yet, because:
(a) there is no hardware supported
(b) it cannot be interfaced

(For more information about the supported hardware, see 204.txt)

DISPLAY/PRINTER 0.10 is supplied under the GNU-GPL license, and it admits easy
adding of other hardware types, by just implementing the routines that do the
hardware codepage replacement. For more information, you should read the
FreeDOS technote 204, which is included in this documentation (as 204.txt).


3.- 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


4.- How to use the program
==========================

Simply run it, being 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[:]=(hwtype,n,m)

where:
   devname a valid device name, that in this version is ignored
           (use ANY valid name, such as CON)
   hwtype  a valid hardware type identifier, such as EGA or VGA
   n       hardware codepages: indicated as a simple number, or as a list
           of numbers (n1,n2,...) if more than one are to be used
   m       software codepage buffers and subfonts. It can specify simply
           a number (number of codepage buffers), or a pair (b,f) with the
           number of codepage buffers and the number of subfonts (a subfont is
           a font with a different size, e.g. 14 or 16 rows per character). If
           the number of subfonts is ommited, then the most appropriate number
           will be detected.

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 the MODECON.EXE program provided. In the
future, MODECON will be merged to FD-MODE.

DISPLAY does not offer the possibility to unload once loaded.


5.- Known limitations
=====================

The following limitations apply to DISPLAY/PRINTER 0.10:

- Currently, the driver only admits DISPLAY-type CPI files, uncompressed and
with simple contents (e.g. not admitting those having more than three subfonts
per codepage)
- It can only change one codepage at a time
- It does NOT interface with IOCTL calls, so it does NOT work with other MODE
  programs than MODECON.EXE

These two are to be overcome on versions 0.10 and 1.0 respectively.


6.- Using MODECON.EXE
=====================

Use the accompaining MODECON.EXE utility to communicate with the
program. It is self-explanatory (issue MODECON /? to see the options).
There are three main commands that allow you to interface with DISPLAY.

The first one is to know the currently active codepage:

MODECON CODEPAGE

Will tell you which is currently active codepage. Hardware BIOS codepage
is allways supposed to be 437 (for the moment), which corresponds to the
state of inactivity of the driver. DISPLAY always starts inactive.

A second command allows you to PREPARE a codepage, i.e., to load the
codepage information that DISPLAY needs to operate. The information is
loaded from a CPI file. For example, if you want to prepare DISPLAY to use
codepage 850 from EGA.CPI, you have to issue

MODECON CODEPAGE PREPARE (850) EGA.CPI

which will load the codepage 850 into the first buffer from the EGA.CPI file.
You use a list format to load ONE codepage into a desired buffer. For example,
if we have specified 2 buffers, we can load codepage 850 into the second one by

MODECON CODEPAGE PREPARE (,850) EGA.CPI

Other useful command is to make active certain codepage. Hardware codepages can
always be selected. Any other codepage needs to be prepared beforehand. If we
have prepared codepage 850 with the previous command, then make it active by

MODECON CODEPAGE SELECT 850

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:

MODECON CODEPAGE REFRESH

Please always read the fast help of MODECON program to know more about it.


7.- Future wishes
=================

In a nearby future, I'll be considering these tasks:

(1) Be able to load more than one codepage (expected by 0.11)

(2) 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=...
- save prepared CP buffers to XMS or EMS
- read DRFONTs and more options from CPI files
- (DISPLAY.SYS) communicate with ANSI.SYS via IOCTL calls
- (PRINTER.SYS) enable the Privileged Lock Codepage Switching feature


<<<EOF>>>