   This file documents the Linux MS-DOS emulator version 0.49.

   Copyright (C) 1993 Robert Sanders

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies (see the GNU General Public License).

Video Configuration
===================

   This section describes the run-time configuration options pertaining
to dosemu's display.  See Run-time Configuration, for an
introduction to the configuration file.

   The `video' word begins a list statement which specifies the
combination of techniques dosemu is to use to provide a video display.
The general format is this:
     `video' { [VALUE ARG] ... [PREDICATE] ... }

   These are the video words:

 - Predicate: VGA
 - Predicate: EGA
 - Predicate: CGA
 - Predicate: MDA
     Informs dosemu of the particular type of color display physically
     present in the machine.  EGA/CGA are treated identically, while
     VGA must be enabled for graphics to work (this may change).

     MDA is different from the EGA/CGA only in that it uses a different
     address range for display memory.

     BUG: the MDA directive currently does not work.  I hope to have
     this fixed fairly soon, but I need volunteers to help (hint hint).

 - Value: Chipset TYPE
     Specify the chipset used in the SVGA card.  Currently, only S3,
     TRIDENT and ET4000 are supported.  The word TRIDENT refers to the
     T8900C; other models may or may not work. Support for S3 chipsets
     is not yet complete. If you use it and it does not work correctly,
     please write a mail to niemann@swt.ruhr-uni-bochum.de.

 - Value: Chunks NUMBER
     Specify the granularity with which dosemu will examine text mode
     lines for change when updating non-console screens.  A value of 1
     causes dosemu to update the entire line if it has changed; a value
     of 4 causes dosemu to update only the quarter portions of the line
     that have changed.  Too high a value may cause performance
     degradation because of the overhead of cursor positioning.
     Default is 1.

 - Predicate: Console
     Causes dosemu to activate the features only available on the
     console *if* dosemu is being run from the console.  These features
     include direct screen updates and graphics support.

 - Predicate: FullRestore
 - Predicate: PartialRestore
     FULLRESTORE causes dosemu to save all the card's state and memory
     upon a console switch.  PARTIALRESTORE only saves that part of the
     memory which may be altered by text-mode Linux.  PARTIALRESTORE is
     sufficient unless one is running the X Window System concurrently
     with dosemu.

 - Predicate: Graphics
     Allows dosemu to use graphics modes.  At present, this only works
     with VGA cards.  Note that, unless the proper SVGA chipset is
     specified along with this predicate, dosemu may incorrectly
     restore SVGA text modes when switching Virtual Consoles and
     exiting.  For example, dosemu works perfectly with my ET4000 when
     in the 100x40 mode, but does not properly restore the 132x25
     screen.

 - Value: MemSize SIZE
     Specifies the amount of memory present on the VGA card in units of
     kilobytes.  Typical values are 128, 256, 512, and 1024 kilobytes.

 - Predicate: VBIOS_copy
 - Predicate: VBIOS_mmap
 - Value: VBIOS_file FILENAME
     These three predicates specify the method dosemu will use to obtain
     access to your VGA BIOS ROM.

     VBIOS_MMAP causes dosemu to use the `mmap' system call to directly
     map the BIOS into the dosemu process's address space.  This has
     the advantage of making the ROM write-protected, and is slightly
     more memory efficient.

     VBIOS_COPY causes dosemu to copy the entire ROM from `/dev/mem'
     into the dosemu's address space.  As this moves all of the video
     handling code from slow ROM into fast RAM, this method will
     probably give better performance.  Think of this as dosemu's
     built-in BIOS shadowing.

     VBIOS_FILE causes dosemu to read the disk file FILENAME into
     memory.  This is useful for experimenting with alternate BIOS
     images.  To create a file calle `vbios' with an image of your BIOS
     ROM in it, execute the following command as root:
          /etc/dosemu/getrom > vbios

     See BIOS, for an explanation of why these directives are
     necessary.

     VBIOS_MMAP and VBIOS_COPY both require that the file `/dev/mem'
     exist and be a character special device that accesses Linux kernel
     memory.  dosemu must be installed suid root to read this file.

   *NOTE:* some video cards may require additional configuration
information to function correctly.  For example, the ATI Wonder VGA card
requires this line:
     ports { 0x1ce 0x1cf }

Peripherals
***********

Serial Ports
============

   The emulator provides some support for both BIOS-accessed and direct
hardware-accessed serial ports.  I will primarily discuss the latter,
as the former is rarely used.

   The serial ports may be used to provide access to the system's mouse,
modem, or other serial device.  While the emulation of the UART (1) is
as faithful as necessary, there are some features which are not yet
emulated:

   * Overrun, framing, and parity errors.  Overrun should never happen.
     The other errors are difficult to detect from the termios
     interface.

   * The modem control lines (DTR, RTS)

   * Loopback is only partially emulated

   * the 16550's FIFOs (2)

   You may use any Linux character device special file as a serial port,
although certain features will only work correctly on tty devices.
dosemu only supports the simultaneous use of two serial ports.

   The current implementation comfortably supports my 1200 baud serial
mouse; however, it chokes on continuous 9600 baud data.  The problem is
an obvious-though not simple-one, but I doubt I'll rush to fix it
unless people have mouse-related problems.  Don't expect too much from
the serial emulation; it's intended for mouse usage, not ka9q.

Serial Port Configuration
=========================

   This section describes the run-time configuration options pertaining
to dosemu's virtual serial ports.  See Run-time Configuration, for
an introduction to the configuration file.

   The `serial' word begins a list statement which specifies the
operation of the virtual serial ports.  The general format is this:
     `serial' { [VALUE ARG] ... [PREDICATE] ... }

   These are the serial words:

 - Value: Device DEVNAME
     Causes dosemu to treat the character device special file DEVNAME
     as a virtual serial port.  The defaults are `/dev/cua0' for the
     first serial port and `/dev/cua1' for the second serial port.

 - Value: Base PORT
     Sets the virtual UART's base port address to PORT.  The defaults
     are 0x3f8 for the first serial port and 0x2f8 for the second
     serial port.

 - Value: Interrupt INTNUM
     Sets the virtual UART's interrupt vector number to INTNUM.  The
     defaults are 0xc for the first serial port and 0xb for the second
     serial port.

 - Predicate: Modem
 - Predicate: Mouse
     These options specify the method of resource-sharing dosemu is to
     employ.

     The mouse directive does not work in the 0.49 release.  You will
     not be able to share the mouse with another program such as X11.

     MODEM causes dosemu to open the virtual serial port's device at
     "bootup" and keep it open until dosemu is shutdown.

     MOUSE causes dosemu to treat the virtual serial port as a shared
     resource which always belongs to the program running on the
     foreground virtual console.  dosemu will open the virtual serial
     port's device when it's console is made current and release it
     when its console is switched away from.  This only applies to
     console video, of course.

     BUG: the MOUSE directive does not work in dosemu 0.49.  I hope to
     have this fixed fairly soon.

   ---------- Footnotes ----------

   (1)  Universal Asynchronous Receiver/Transmitter, the support chip
through which all serial transactions are made

   (2)  First In, First Out: a 16-byte queue the 16550 UART uses to
provide more efficient character transfer by reducing the number of
serial interrupts which must be serviced

Printers
========

   dosemu can emulate up to three printers accessed through interrupt
0x17 BIOS calls.  These printers may only be accessed through the BIOS;
dosemu makes no attempt to emulate a parallel port (1)  Each virtual
printer may be configured separately to act in one of three ways:

  1. Save all output to a disk file

  2. Send all output directly to some device

  3. Send output in groups to some external program, such as the Linux
     `lpd' daemon.

   *Method 1* is naive, but ensures that print jobs are not split
unnaturally.  All of the session's printer output for that printer will
be sent to the specified disk file.

   *Method 2* is not recommended, but can be used to control a directly
connected printer without intermediate print handlers.

   *Method 3* is the most useful and sophisticated, but requires some
user effort to configure.  Under Linux, you will most probably use the
default setup for LPT1:, with perhaps some additional options.  The
default timeout of 8 seconds may be too long or short for you; adjust
it to best fit your application.

   What happens on timeout:

   If using methods 1 or 2, then the file will simply be flushed and
closed until further output happens.  Upon further output, the same
file will be appended to.  When dosemu is exited, the file will remain
in the state it was before exiting: device files will remain device
files, and normal files will remain normal files which just happen to
contain all the accumulated printer output.

   If using method 3, the temporary file that dosemu has chosen will be
flushed and closed.  The printer command will be invoked with the option
string processed to replace the first occurrence of "%s" with the
filename, after doing which dosemu will delete the temporary file.

Printer Configuration
=====================

   The `printer' word begins a list statements which adds a virtual
printer device dosemu's configuration.  This is the general format of
such a statement:
     `printer {' [PREDICATE] ... [VALUE ARG] ... `}'

   These are the words which may be used within the printer list:

 - Value: Command CMD
     tells the virtual printer which Linux command to call to print a
     file.  The default is `lpr'.

 - Value: Options OPT
     tells the virtual printer the option string to pass to the print
     command.  The string "%s" will be replaced with the filename (this
     is necessary!).  The default is "%s".

 - Value: Timeout SECS
     sets the printer timeout to SECS seconds.  This is the amount of
     time the virtual printer device must sit idle (2) before sending
     the accumulated output to the print command as a file.

 - Value: File NAME
 - Value: Device NAME
     Will cancel the "wrapup and send job to lpr" type of virtual
     printer handling for the relevant printer, and configure dosemu to
     simply save all characters in the file named NAME, or send
     characters to the device named NAME.  The timeout parameter is
     still used to determine when to flush the printer buffer to the
     file or device.

   A sample section of a configuration file:

     ; this is the printer section of /etc/dosemu/config
     ;
     printer { command "lpr" options "-p %s" timeout 8 }
     printer { file "dosemulpt2" timeout 10 }
     printer { device "/dev/lp1" timeout 3 }

   Here, lpt1 is configured to send printer jobs to `lpr' with the
pr-format option after a timeout of 8 seconds (method 1); lpt2 saves all
output to the file `dosemulpt2' with a buffer flush every 10 seconds
(method 1), and lpt3 flushes all output to the `/devlp1' device every 3
seconds (method 2).

   *NOTE:* Make sure that there exsists a directory called `/usr/tmp'
with the world-execute, world-read, and sticky bits set.  The
temporary-file calls in lpt.c need this directory to store files in.
The best way to create this if you don't have it is this:
     mkdir /usr/tmp
     chmod 1777 /usr/tmp

   ---------- Footnotes ----------

   (1)  I do not believe such a feature is necessary.  If you have need
of parallel port emulation, let me know and I'll see whta I can do.

   (2)  i.e. receive no characters

Disk Redirector
===============

   While most DOS users will already have an MS-DOS partition containing
the "operating system" (sic), and assorted utility, application, and
game packages, it is desirable for dosemu to allow DOS to access native
Linux filesystems transparently.  That is, dosemu has the ability to
offer any Linux directory as a disk for MS-DOS to access as it would any
other.  This not only facilites file transfer between the two operating
systems, but it helps wasted disk space: DOS and Linux can share a
single file system, so that no space goes unused on either side.  The
operation of making a Linux file system available to DOS is called
"redirection", thus the program to do that is called a "redirector".
Users of PC-NFS, Novell Netware, or CD-ROM drives and MSCDEX will
recognize this class of software.

   Dosemu versions earlier than 0.49 used a program called `LINUX.EXE'
to provide drive redirection.  However, that program had several fatal
faults, which are listed here:

   * `LINUX.EXE' was based on a program called `PHANTOM.PAS', which was
     published in Andrew Schulmann's `Undocumented DOS'.  As dosemu is
     intended to be a freely available program, inclusion of copyrighted
     code is ... discouraged.

   * `LINUX.EXE' suffered from several bugs, the most annoying of which
     was the inability to execute `.exe' files from a redirected file
     system.

   * Because of the possibly copyrighted nature of `LINUX.EXE', your
     humble author was for a long time unable to find the source to it,
     and was thus unable to fix even the most trivial of its bugs.

   In order to use the disk redirector, make sure that your boot disk
contains the file `emufs.sys'.  Also make sure that the `config.sys'
file on your boot disk has a line like this one:

     device=emufs.sys DIRECTORY [FLAG]

for every redirected drive you wish to be configured.  DIRECTORY is the
Linux directory you wish to appear as a DOS network drive.  emufs.sys
automatically assigns the next available drive letter to it.  FLAG is
the optional letter `R' to specify that you want the drive to be
read-only.

   Now, you ask, what if I want to access my DOS disk this way instead
of my Linux disk?  I mean, what good are Linux files going to do me?
Well, here's the trick: you can mount a DOS partition on a Linux
directory using the Linux Virtual Filesystem magic (no need to concern
yourself with the technical details).  Thanks to Werner Almesberger's
excellent MS-DOS filesystem in the kernel, you can use the normal Linux
mount command to do this.  For example, let's say you have two dos
partitions, /dev/hda1 and /dev/hdb3.  Do this on the Linux side:

     mount -t msdos /dev/hda1 /dos1
     mount -t msdos /dev/hdb3 /dos2

   This mounts the DOS partition /dev/hda1 over the Linux directory
/dos1, and the DOS partition /dev/hdb3 over the Linux directory /dos2.
Now you can use the MFS disk redirector to access the DOS disks by
telling it to use /dos1 as the root directory of the first DOS drive,
and /dev/hdb3 as the root of the other.  And, just for kicks, you want
to allow read-only access to your Linux kernel sources from dosemu.
Put these lines into your config.sys and reboot dosemu:

     device=c:\emufs.sys /dos1
     device=c:\emufs.sys /dos2
     device=c:\emufs.sys /usr/src/linux R

   Assuming you only have C: drive already defined, this will give you
/dos1 as read-write drive D:, /dos2 as read-write drive E:, and
/usr/src/linux as a read-only drive F:.

   *NOTE:*  You will still need some "image"-type drive to boot from.
This drive will either be your virtual floppy drive A: or a virtual
hard drive C:.  See Booting, for more information on the types of
drives from which dosemu can boot.

   Andrew Tridgell (`tridge@nimbus.anu.edu.au') "ported" the Mach DOS
emulator's redirection code to dosemu.  I translated his modified
`linux.asm' into a format acceptable by Bruce Evans' as86 assembler;
this is the file `emufs.S'.  Any mistakes in emufs.S are probably mine.
See Mach.

   To generate `emufs.sys' from the source code, you'll need as86 and
ld86.  These should come compiled with the SLS distribution of Linux,
and can also be found in source form in the file `bin86.tar.Z',
available on *tsx-11.mit.edu* and other fine Linux (and perhaps Minix)
archives.  You also need as86/ld86 to build the Linux kernel, so if you
can build the kernel, you know you already have them.

   Andrew also made these extremely useful enhancements and bugfixes to
the redirector:

   * the original port to dosemu

   * sane mapping of DOS attributes to Linux attributes

   * sane handling of uid/gid when run suid root

   * integration of the two DOS programs that Mach used--(`machfs.sys'
     and `mfsini.exe')--into one program for Linux (`emufs.sys').

   * the ability to handle multiple redirected drives

   * the command line syntax of `config.sys' described above,

   * the read-only flag for redirected drives

Hard Disks
==========

   My current setup in emu.c has two hard disks: hdimage (C:) (1), and
direct access to my DOS partition (D:).  It has two floppies, a 1.2 MB
floppy (A:), and a 1.44 MB floppy (B:).  I currently Look in the
Makefile to specify your particular floppy configuration.  See
Configuration, Disk Images, for further information about
floppy configuration.

   The `hdimage' and `diskimage' files must exist at dos invocation
time if dosemu references them.  Only one of them need be bootable; and
they can be of any size.  In fact, with this installation, you only
need to type `touch diskimage'" in the dosemu directory to make it
work.  You may then format the A: disk to make "diskimage" into an
accessible disk.  The disk/hd-image will grow to accomodate your usage
of it (but will not shrink!)

   You can give dosemu direct access to your hard drive, without using a
redirector, so that MS-DOS uses normal int13h calls to read and write
sectors.  For this option, of course, you must have at least one
partition on that hard disk containing a MS-DOS filesystem.  This isn't
a problem, as the utility of this feature lies in being able to use the
same disks for dosemu that you use for native DOS.

*WARNING WARNING WARNING WARNING WARNING WARNING*
You may *not* give dosemu direct access to an MS-DOS partition that is
also mounted as a Linux filesystem!  Very Bad Things will ensue!  Linux
will be confused by a filesystem that changes without Linux asking it
to change, and MS-DOS will probably be too stupid to notice--thereby
corrupting whatever you doomed by trying such a silly thing.

   It is for this reason I recommend using the Disk Redirector if at all
possible.  This *will* let dosemu share access to a Linux-mounted
MS-DOS partition.
*WARNING WARNING WARNING WARNING WARNING WARNING*

   If you have an entire hard drive dedicated to MS-DOS, look into
Whole Disk Access; however, if your hard disk shares both DOS and Linux
partitions, as mine does, Single Partition Access might be better
suited to your system.

   Better yet, scrap the whole direct access thing altogether and use
the MFS redirector to access your DOS hard disk through Linux.  See
Disk Redirector, for an explanation.

   ---------- Footnotes ----------

   (1)  The drive names in parentheses refer to the dos emulator's view
of the world, not your normal, real-DOS letters.

Whole Disk Access
-----------------

   Whole Disk Access allows dosemu to directly read an MS-DOS filesystem
from a *disk* block device (*not* a partition device!).  This means
that, if you have a DOS partition somewhere on your first hard drive,
you could set up dosemu to find that partition on `/dev/hda'.  This
feature is deprecated and pretty much undocumented.

   Whole Disk Access gives dosemu access to, well, the whole disk.  This
includes the Master Boot Record and every partition on the disk.  You
may boot from a disk configured with WDA, but I don't recommend it.  In
particular, LILO boots on my system if I try this; it will not, of
course, boot Linux under dosemu.

   dosemu is configured by default to attempt auto-detection of your
hard disk's geometry by querying the Linux kernel.  This may or may not
work for non-IDE drives.  If it does not work correctly, you will have
to enter the geometry explicitly in the configuration file.

   See Run-time Configuration, for more information on configuring
your hard disk.  Here's an example config line for my hard disk setup:
     disk { wholedisk /dev/hda1 }

Single Partition Access
-----------------------

   Single Partition Access (hereafter abbreviated to SPA, which may or
may not be a registered trademark of Robert Sanders, Megaconglomerated)
is very much like Whole Disk Access.  dosemu used a block disk device
to access the disk on a sector level and DOS sees the partition as a
normal int13-accessible drive (i.e. non-network).

   However, the difference lies in the fact that dosemu uses a different
block disk device; Whole Disk Access needs the the Whole Disk devices
like `/dev/hda', while SPA access the Partition devices like
`/dev/hda1'.  The main difference between these two is that `/dev/hda'
can access any part of the disk, while `/dev/hda1' can only access the
area of the disk allocated to its specified partition.

   Using SPA access is much safer than using WDA if you're worried about
dosemu going ape all over your important data.  I have my Linux and DOS
partitions on the same drive, so this feature is a big win for me.
Your mileage may vary.

   Single Partition Access gives access to what DOS calls *primary*
partitions only.  You may not enable access to logical partition within
an *extended* partition.  If there is enough need for this feature I
may add it.  You may boot from an SPA partition.

   To set up dosemu for SPA access, follow this procedure:

  1. Run the included program mkpartition to read the partition data
     from your hard drive.  mkpartition takes two arguments, both
     mandatory: the whole disk drive device, and the partition number
     within that drive.  For example:

          mkpartition /dev/hda 1

     sets up the `/etc/dosemu/partition' configuration file for SP
     access to the first partition of the drive (`/dev/hda1').

  2. Add a line to the `/etc/dosemu/config' configuration file like
     this:
          disk { partition /dev/hda1 1 }

   See Configuration, for more information on the files in
/etc/dosemu.

Disk Images
===========

   Everyone seems to ask this: "How do I create diskimage/hdimage"?
Well, it isn't really that complicated.

   Image files of both types must reside in the directory from which you
start dosemu, at least with the standard installation.

Creating hdimage
----------------

   Follow these steps to create an image hard disk for Linux dosemu.
This hard disk will act like a native DOS formatted hard disk drive.

  1. First, you must create the actual `hdimage' file.  dosemu has a
     special format for hard disk image files: each one has a 128 byte
     header which tells dosemu the disk's format.  dosemu is supplied
     with a program to create an `hdimage' of any size.

     Invoke `mkhdimage' with the proper parameters to create the size
     image file you desire.  Currently the `mkhdimage' program only
     accepts head, sector, and cylinder counts; all arguments are
     optional, and `mkhdimage', and the default is to create a 1
     megabyte drive.  Make sure you redirect the standard output of
     `mkhdimage' into the `hdimage' file; otherwise you will see
     gibberish.

     This command generates a hard disk image file with a geometry
     corresponding to that of a real hard disk with 12 heads, 17 sectors
     per track, and 300 cylinders.

          mkhdimage -h 12 -s 17 -c 300 > hdimage

     At 512 bytes per sector, this equals a roughly 29 megabyte drive.
     This is probably too large for most needs; if you need this much
     space, consider using the disk redirector.  See Disk Redirector).

  2. Once the hdimage file is created, you must run DOS fdisk to create
     a partition.  Then you exit the emulator, reenter it, and format
     the C: drive.  You can make the disk bootable with the /s
     parameter to format, a shown in the example below:
          format c: /s
          fdisk /mbr

     The second line is necessary because of the custom boot sector on
     the current distribution hdimage.  I will probably fix this before
     the real release of 0.49.

Creating diskimage
------------------

   There are two ways to create an image of a floppy (`diskimage') file
for the Linux DOS emulator.

  1. To create an image file whose contents are a copy of an already
     existing, real floppy drive, simply copy the entire disk into a
     Linux file.  For example, this command copies the disk from
     /dev/fd0 into the file `diskimage':

          dd if=/dev/fd0 of=diskimage bs=16k

     Make sure that the configuration of dosemu properly understands
     what type of floppy the file was copied from.  Once that is done,
     this diskimage is ready to use.  See Configuration

     If your original disk is bootable, so will `diskimage' be; this is
     an excellent way to create a boot disk for dosemu.  (To boot from
     this disk, invoke dosemu with the `-A' switch, which tells dosemu
     to boot from the `A:' drive.) See Booting

  2. To create a blank floppy image file which you will then format
     under dosemu, simply execute this command:

          touch diskimage

     This creates a 0-length file called `diskimage' in the current
     directory.  To use this file, you must enter dosemu and format it
     for use under MS-DOS.  This command will format it and make it
     bootable:

          format a: /s

Disk Configuration
==================

   The `disk' and `floppy' words begin list statements which add a disk
or floppy to dosemu's configuration.  This is the general format of
such a statement:
     `disk'    { [VALUE ARG] ... [PREDICATE] ... }
     `floppy' { [VALUE ARG] ... [PREDICATE] ... }

   Some words within these statements are only useful for hard disk
configuration:

 - Value: image FILE
     Specifies that the disk is to be configured as an hdimage type file
     called FILE.

 - Value: partition PARTDEV PARTNUM
     Specifies that the disk is to be configured as a directly accessed
     partition, which Linux accesses as device special file PARTDEV;
     the cardinal partition number PARTNUM, which must be between 1 and
     4, is the partition's number in the partition table.
     See Single Partition Access

 - Value: wholedisk DISKDEV
     Specifies that the disk is to be configured as a diretly accessed
     disk, which Linux refers to as device special file DISKDEV.
     See Whole Disk Access.

   Some words are only useful for floppy disk configuration:

 - Predicate: threeinch
 - Predicate: fiveinch
     Specifies whether the floppy drive should show up in the CMOS
     configuration as a five inch (1.2 MB) drive, or a three inch (1.44
     MB) drive.

 - Value: Device DEV
     Specifies the device DEV as the floppy disk.  DEV may be either a
     block special device which points to a real floppy disk, or a
     floppy disk image.  See Creating diskimage.

   These words apply to both floppy and hard disks:

 - Value: Sectors COUNT
     Configures the specified disk to have COUNT sectors.

 - Value: Heads COUNT
     Configures the specified disk to have COUNT heads.

 - Value: Cylinders COUNT
     Configures the specified disk to have COUNT cylinders.

 - Predicate: readonly
     Sets the relevant disk to read-only mode.  This still behaves
     strangely.  See Bugs, for more information.

   *NOTE:* it should be unnecessary to specify the geometry of a disk
for real hard disks, partitions on such disks, real floppy drives, or
new-style hdimage files.  In other words, only floppy image files
should need a geometry specification.

Memory
******

   dosemu supports several kludgy methods that pseudo-allow MS-DOS to
"break the 640K barrier," as the adverts like to say.

DOS memory
==========

   If you need extra memory, you can use the "-m" switch to set the
memory size.  This switch specifies, in Kilobytes, how much main memory
the emulator has available.  The default is 640, although the emulator
allows up to 734.  I believe that 734K is safe, although too much over
that intrudes on the screen memory at b800:0000.

   This option is incompatible with VGA video, so specifying VGA
through either of the option methods will set the base memory size to
640K.  If you need additional DOS memory, look into XMS and EMS.  See
XMS, EMS., for more information on increasing the amount of
free memory.

XMS
===

   Adam Goldberg (`adamg@microware.com') was kind enough to send me the
XMS 3.0 specs so I have, to the best of my knowledge, implemented the
entire XMS 3.0 specification.  This includes:

   * Extended Memory Block (EMB) Functions

   * Upper Memory Block (UMB) Functions

   * High Memory Area (HMA) Functions

   * 32-bit Extended Memory Block Functions (new with XMS 3.0)

   You can specify the maximum amount of memory the emulator can use in
two ways: through the `-x' SIZE command line option, and through the
run-time configuration file (see Memory Configuration.).  SIZE is
given in kilobytes.

   If you enable XMS, you can put the line

      dos=high,umb

in your `config.sys' to allow MS-DOS itself to use the extra memory.
Using XMS along with this line, I have well over 600K of memory left
for DOS executables; with both SMARTDRV and RAMDRIVE loaded high I have
621K of memory left for DOS executables.

   You cannot and need not run any other XMS driver, such as HIMEM.SYS.
dosemu uses its own internal driver to provide XMS services.

EMS
===

   A partial EMS implementation is also present; I say "partial"
because it implements version 3.2 of the Expanded Memory Specification,
which is extremely old.  The newer version, released in 1987, is EMS
4.0.  I am currently working on extending the dosemu implementation to
EMS 4.0.

   The dosemu EMS implementation was based on the Mach DOS emulator's
EMS implementation, which provided version 3.2 of the
Lotus/Intel/Microsoft Expanded Memory Specification. [Ed: oh, the
bletchery!]  See Mach, for more info about Mach.

   You can specify the maximum amount of memory the emulator can use in
two ways: through the `-x' SIZE command line option, and through the
run-time configuration file (see Memory Configuration.).  SIZE is
given in kilobytes.

   EMS requires a kernel patch, included with dosemu.  It adds an
`mmap()' operation for the device /proc/self/mem, which dosemu uses to
manipulate regions of its address space.

   You cannot and need not run any other EMS driver, such as EMM386.EXE.
dosemu uses its own internal driver to provide EMS services.

Memory Configuration
====================

   These are the configuration words which pertain to dosemu's memory
management.  See Run-time Configuration, for an introduction to the
configuration file.

 - Value: DOSmem SIZE
     Sets the base DOS memory size to SIZE kilobytes.  Default size is
     640k.   The maximum is 734K.

 - Value: EMS SIZE
     Activates Expanded Memory Specification 4.0 emulation with a
     memory pool size of SIZE kilobytes.

 - Value: XMS SIZE
     Activates Extended Memory Specification 3.0 emulation with a
     memory pool size of SIZE kilobytes.

   If you wish to explicitly disable XMS or EMS, you may specify its
control word and the parameter NONE.  The default for both is to be
disabled.

Miscellaneous
*************

   These are some marginally useful or outright useless options that I
haven't gotten around to removing from dosemu.

BIOS
====

   The "-b" option maps the video BIOS ROM at c000:0000 into the
emulator's address space. (1)

   Do not use this option unless necessary, as the XMS Upper Memory
Block support uses the address space normally occupied by the ROMs for
Upper Memory Blocks; mapping in the BIOS reduces the amount of memory
available for XMS.  See XMS, for more information about Upper
Memory Blocks.

   *NOTE:* You may suffer ROM corruption problems if your computer uses
shadow ram to speed BIOS access times.  If this happens, turn off ROM
shadowing in your system's CMOS setup (2).

   Alternately, you may use the VBIOS_COPY and VBIOS_FILE video
directives.  See Video Configuration, for more information on ways
to prevent BIOS corruption.

   ---------- Footnotes ----------

   (1)  This option is automatically activated by using BIOS-driven
video.

   (2)  Linux can run into other problems if you have shadow ROM
enabled, so it's always a good idea to turn it off

CPU type
========

   Many DOS programs act differently when run upon different Intel
processors; for example, a program might use the 32-bit registers
available on the 386, while on the 286 it makes do with 16-bit
registers.

   The canonical method of differentiating between the different
processor types is explained in the `Intel 486 Programmer's Handbook'.
Suffice it to say that the test relies upon various instruction
peculiarities and the behavior of bits in the `eflags' register.  While
dosemu cannot emulate the former, the latter is easy to emulate using
the techniques available through virtual-8086 mode.

   These are the dosemu command-line switches to choose the processor
mode:

`-2'
     act as an 80286

`-3'
     act as an 80386 (default)

`-4'
     act as an 80486

   The run-time configuration file may also be used to select the
processor to be emulated.  See Run-time Configuration.

   Because of a combination of circumstances, it is possible to make a
386 show up as a 386; it is possible to make a 486 show up as a 386.
It is possible to make a 486 test as a 486, but I have not tested
whether it is possible to make a 386 test as a 486 (although it should
work, it is not recommended).  Most programs are naive enough to
believe that my 486 is a 286 when I select that option, but Turbo
Debugger, for example, notices the 32-bit registers and is not fooled.

TTY copy
========

   The "-P TTY" sends a copy of _dbg_ (the debugging messages) to a
terminal.  It can be left out if you wish (or have nothing to send it
to!).  This is no big deal, basically just a tee.  The reason it's
there at all is that it will one day provide me with an interactive
debugging system.  (One day, like everything else :-).

Programs That Work
******************

   Try to save the debugging messages for any bugs or problems that you
find.  They are more helpful to me than descriptions alone.  See
Debugging Messages.

   DR-DOS 6.0 apparently works under the emulator.  I have been told
that, because it uses a variety of temporary files, your boot disk
(whatever it may be) should be un-write-protected. If you have any
problems, write me.

   People have had some success using Stacker or SuperStor to access
their compressed "partitions" under the emulator.  I don't have either
of these programs, haven't tried them, and most definitely won't
guarantee that they'll work.  However, you are free to experiment.

   Here are some programs that I use/test under dosemu:

   * Turbo Pascal 5.5

   * PC Tools PCShell (and compress)

   * QEdit

   * Borland TASM/TLINK

   * doskey (might not be impressive, but it's useful)

   * 4DOS 4.0

   * HelpPC 2.1

   * a86 and d86 (a shareware assembler and debugger)

   * WordPerfect 5.0

   * Microsoft Word 5.5

   * Norton Utilities v6.0 (1)

   * Checkit

   * Turbo Debugger 3.0

   * A very old version of Turbo C

   * pkzip 2.04e

   * MKS utilities

   * Elvis 1.5

   * SimEarth

   * ColorView/386

   * Telix & Kermit (at low baud rates)

   * MouseSystems mouse and MicroSoft mouse driver (mscmouse.com)

   * dBase III+

   Here are some programs that are *reported* to work:

   * DR-DOS 6.0

   * SuperStor

   * Stacker

   * uEmacs (don't even think about demacs!)

   * Minitab

   * the Big Mouth Voicemail card (2)

   * Managing Your Money,

   * Quicken 4.0

   * FoxPro 2.0

   * Microsoft Word 5.0

   * Turbo C++ 1.0

   * Alpha-4 2.1 (database)

   * Microsoft Multiplan 4.2

   * Lotus 123 v2.2

   Also, see section VGA for a listing of programs that work
using graphics and extended text modes.  Once the new VGA emulation is
more thoroughly integrated into dosemu I will incorporate that list of
programs here.

   ---------- Footnotes ----------

   (1)  Go into configuration and turn off "Zooming Boxes" under the
Video menu.  This really speeds things up.

   (2)  Ed Carp, erc@apple.com posted some patches to get it to work

Bugs
****

   I probably already know about the *lack of features* in dosemu, so
please don't tell me "It won't recognize my mouse."  However, if you do
find some failure that you think ought to work, *please* do write me
and tell me about it.  Also, if you have some fairly simple feature
that you really need, I can be flexible.

   If you need to reach me, I can receive e-mail at this Internet
address:

     gt8134b@prism.gatech.edu

   I'm sorry about the gobbledygook address, but my lovely educational
institute doesn't see fit to give human names to non-computer science
majors.

   Also, I frequent the MSDOS mailing list; I answer questions posted
there, and post dosemu updates and announcements there.  To find out
more about the mailing lists, send mail to
`linux-activists-request@niksula.hut.fi' with a message body of `HELP'.

   My implementation of EMS 4.0 (based on the Mach implemetnation of EMS
3.2) seems to have a few bugs; they have only manifested as errors when
using PKZIP in conjunction with RAMDRIVE.SYS.  If you have the choice,
use XMS instead of EMS; not only is it (paradoxically) faster to use
XMS, it's safer (easier implementation and it's been tested longer).
Also, many EMS 4.0 functions aren't implemented, which could cause
problems.

   The VGA save/restore code for console switching while in SVGA modes
only handles S3, Trident and ET4000 chipsets, and the ET4000 portion of
it is slightly buggy.  In addition, the Trident section fails to
correctly restore the screen on at least the Trident 8800.

   Non-console video still suffers from a bug that causes it to
incorrectly update areas of the screen.  This will hopefully be fixed
soon.

   As mentioned before, the MOUSE and MDA configuration file
directives--and their corresponding features--do not work.

   I've fixed too many dosemu0.4 bugs to count, so I won't list them
here.  I've probably introduced as many, though, so watch out.

   I occasionally hear of some program that used to work, but doesn't
now.  Please, mail me with the name of the program, what it does (and
how it does it, if you have any idea), and the behavior before and now.
I'll try to get it working again, but no promises.

   If the emulator crashes on you, the first thing you should do is
examine the dbg file for any line beginning with `ERROR:'; look at the
last such line first.  If you can't find any suspicious lines, try
recreating the crash with full debugging-messages (i.e. specify `-Da'
as a parameter to dosemu).  You'll get a file full of trash, probably,
but at least it's something.

   Sending me reports like "XX doesn't work" really does me no good.
What would be useful is a dosdbg file in which you have noted under what
conditions and actions the bug occurred.  For example comments like:

     /* selected "Turbo Mode" here, screen turned blue */

at the proper points in the dosdbg file are necessary for me to make any
sense of it.

Changes
*******

   This is a list of the changes from dosemu 0.48pl1 to 0.49.  If you
are currently running a version of dosemu 0.48pl1 or older, you need to
make some changes to your configuration to make sure that 0.49 will
work. See Updating from 0.48pl1, for more information on upgrading
your current dosemu installation.

   * Extended XMS 3.0 functions (the 32-bit functions).  XMS is now
     almost done, including UMB functions.  They aren't perfect, but
     they work OK.  See Memory.

   * fixed a nasty bug that sometimes occurred when a key was held and
     repeated

   * added Bill Bogstad's auto-hd-geometry-detection patch. (I would
     probably have never thought of this, as dosemu always has my
     geometry correct, straight out of the box :-)

   * early, buggy mouse support.  Except that it really isn't even a
     mouse yet, just a keyboard mouse. And that doesn't even work.  So
     don't use it.

   * added CPU selection options, -2, -3, and -4.  These make the flags
     register act like a 286, 386, or 486 (this isn't infallible; Turbo
     Debugger 3.0, for example, won't believe you have a 286 no matter
     what flags you try).

   * switched to 2-process model (not really user-visible, except key
     repeat works MUCH better), and using SYSV IPC came with it.
     You'll need Krishna Balasubramanian's ipcdelta package (ipcbeta
     won't do it!) compiled into a 0.99pl7 or newer kernel.

   * using IPC shared memory, I fully and properly implemented the High
     Memory Area.

   * fixed the STI instruction emulation to work as advertised by Intel.
     However, this slows things down some, so I have disabled it by
     default.  #define PROPER_STI in cpu.c to enable it.  Until the DOS
     emulator emulates hardware by generating pseudo-interrupts, this
     option is just useless chaff.

   * fixed the emulator's handling of the IF bit in general.

   * MS-DOS 5.0 no longer exhibits the booting problems it did, so I
     have removed the boot in progress checks.

   * fixed DOS STDIN redirection (i.e. debug < file).  The problem here
     was that dosemu assumed the int21h get-character calls read from
     the keyboard.

   * dosemu now (again) properly supports multiple screen pages, so
     things like Turbo Debugger 3.0 (and previous) now work

   * revamped the Makefile.  you need to do a "make config" after you
     edit the settings in the Makefile. In all honesty, the Makefile
     (unlike dosemu proper) is a bit too feature-laden, but I was
     having fun...  See Configuration.

   * you're all gonna love this one: Andrew Tridgell
     (tridge@nimbus.anu.edu.au) ported the Mach DOS emulator's
     "network" redirector drive code, so now we have a mostly bug-free
     alternative to LINUX.EXE (and no uncertainty about the copyright,
     either).  I would have gotten around to it.  Really.  He's added
     multiple-disk and read-only support.  See Disk Redirector

   * changed the format of hdimage.  It now has a header (currently 128
     bytes) that allows dosemu to use hdimage files with different
     geometries without being recompiled.  See Disk Images.  See
     Updating from 0.48pl1.

   * changed the direct-DOS-disk support to also use partitions instead
     of just disks.  This means that you can tell it to use /dev/hda1
     instead of /dev/hda.  Aside from the added safety of protecting
     your Linux partitions from a possibly insane dosemu running wild
     on the entire disk, this allows you to make your DOS partition
     accessible to a group dos, and make all dosemu users members of
     group dos, etc.  UNIX permissions tricks like that.  I run as
     root, so don't ask me :-) Hard Disks.

   * EMS 3.2 emulation with a kernel patch.  I might have upgraded this
     to EMS 4.0 by the time you read this, or I might not have.  The
     EMS 3.2 "engine" was taken from Mach's DOS emulator and
     bugfixed/modified a great deal for dosemu.  See Memory.

   * fixed a configuration problem (a math coprocessor was being flagged
     when there was none).  By the way, there is a bug in kernel
     FPU-emu in at least 0.99pl7 and previous, so you'll have problems
     if you don't have a 387/486.  The problem is fixed in kernel
     0.99pl8, thanks to two people who independently found and reported
     the problem to me.  Note that dosemu will not work with 0.99pl8
     unless you apply a special patch (the sigdiff patch mentioned
     before; see Configuration, for more information about kernel
     versions and dosemu).

   * more properly handles a monochrome video card with MDA_VIDEO

   * Andrew Tridgell's int16() TAME-like anti-keyboard hogging pause.
     Untweaked, but very effective as is on my 486.  70% CPU -> 2.1%
     CPU for one program.  Numbers will probably be different with the
     new high-resolution Linux timer (when usleep(100) actually means
     something).

   * new printer handler can now send jobs to `lpr' (or whatever other
     command you like).

   * the cheap VGA BIOS demo thing.  See VGA, for details.  Might
     also work for MDA/CGA/EGA, if the card's BIOS shows up at
     0xc000:0000.

   * the -e and -x (EMS and XMS) switches now take a numeric argument
     that specifies (in kilobytes) how much memory to allow for each.
     I will be changing this to use a unified memory pool...

   * added the run-time configuration file parser

   * fixed a problem with the int10h cursor emulation; this most often
     manifested in Borland/Turbo-compiled programs.

   * Serial port emulation.  This allows one to use modems and mice from
     dosemu.

   * Fixes to the int10h code. Much better handling of int10h ah=9/Ah.

   * a lot of little things here and there.