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

Introductory Stuff
******************

   Welcome to the DOSEMU manual!  I hope you can find what you need in
here.

   Let me begin with a general explanation of what exactly dosemu *is*,
before I get too bogged down trying to explain what dosemu *does*.

   dosemu is a user-level program which uses certain special features of
the Linux kernel and the 80386 processor to run MS-DOS in what we in the
biz call a "DOS box".  The DOS box, a combination of hardware and
software trickery, has these capabilities:

   * the ability to "virtualize" all input/output and processor control
     instructions

   * the ability to support the word size and addressing modes of the
     iAPX86 processor family's "real mode", while still running within
     the full protected mode environment

   * the ability to trap all DOS and BIOS system calls and emulate such
     calls as are necessary for proper operation and good performance

   * the ability to simulate a hardware environment over which DOS
     programs are accustomed to having control.

   * the ability to provide MS-DOS services through native Linux
     services; for example, dosemu can provide a virtual hard disk
     drive which is actually a Linux directory hierarchy.

   The hardware component of the DOS box is the 80386's "virtual-8086
mode", the real mode capability described above.  The software component
is dosemu.

   These are the release dates of dosemu:

*0.1, 0.2, 0.3, 0.4*
     These were versions of the original dosemu, written by Matthias
     Lautner.  I based my version--which I now consider the "official"
     version--on his dosemu 0.4.

*0.47*
     January  27, 1993

*0.47.7*
     February  5, 1993

*0.48*
     February 16, 1993

*0.48pl1*
     February 18, 1993

     These versions added console video, raw keyboard, XMS, timer tick,
     VGA attribute fix, simple printer support, BIOS serial ports, and
     lots of bug fixes.

*0.49*
     May 20, 1993 The 0.49 release added EMS, a new disk redirector,
     revamped hard disk support, a more sophisticated printer driver,
     BIOS-driven VGA support, serial port emulation, keyboard TAMEing,
     and lots more bug fixes.

   If you need me, you can reach me at these addresses (1):

     Internet:  gt8134b@prism.gatech.edu

     U.S. Mail:
                Robert Sanders
                38134 GA Tech Station
                Atlanta, GA  30332

   Enjoy!

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

   (1)  Even if you don't need me, you can...

Greetings
=========

   Hello, public,

   This is dosemu version 0.49.  Versions 0.41-0.46 were "internal"
versions, and 0.48pl1 is the public release preceding this one.  The
RCS revision numbers printed in various places throughout the emulator
mean very little to either of us, so don't worry about them.  The
version number (i.e. 0.49) should be printed on the invocation screen,
in case you forget which version this is.

   This is an ALPHA release; dosemu is far from stable.  I do not
expect dosemu to reach BETA stage for quite some time.  However, this
does not mean that you cannot use and enjoy dosemu free of all
problems; it just means that you will be the exception if you do.

   Dosemu 0.49 is based on dosemu0.4 from Matthias Lautner, but is
quite a bit more useable.  It is probably already obsolete by the time
you read this, however, as I am continually at work making the code
even uglier :-).  Hopefully, with all this code uglification will come a
stray feature or two.

Mach
====

   I'm sure that you've all heard the expression "Don't reinvent the
wheel."   Well, it turns out that the kind folks at Carnegie Mellon
University, purveyors of the Mach microkernelish operating system, have
invented a very fine wheel of a DOS emulator.  I did not discover this
until well into my enhancing of dosemu, but it would not have made much
difference: the Mach operating system is sufficiently different from a
traditional UNIX implementation like Linux that a "port" would have
been prohibitively difficult.  The Mach DOS emulator takes full
advantage of the thread capability of Mach, as well as some
emulator-specific features added to the Mach kernel.

   However, several of the subsystems of their DOS emulator are not only
informative to read (which is a great boon in itself), but not *too*
difficult to adapt for usage under Linux dosemu.   As proof of this,
dosemu as of this writing has absorbed two of the Mach emulator's
feature subsystems.  Below is a list, showing the Linux dosemu files on
the left and the dosemu features contained therein:

`mfs.c'
`mfs.h'
`emufs.S'
     the drive redirector (also called the network redirector, as it is
     normally used to provide a remote disk drive over a network
     connection).

`bios_emm.c'
     LIM EMS support. The original Mach DOS emulator file supplied
     version 3.2 of the specification; I have updated it to provide
     version 4.0.

`machsupport.h'
     this is a header file supplying many of the common types and
     functions used in the Mach DOS emulator's files.  Its contents are
     simply the union of the original Mach DOS emulator's files
     `base.h' and `bios.h'

   An added advantage in my integrating code from the Mach DOS emulator
is that, if I modify it carefully so that my Linux-specific changes do
not affect the file when compiled under Mach, and my non-OS-specific
changes work equally well under both Mach and Linux, then I have
effectively benefitted both programs with almost no additional effort.

   CMU placed Mach and the Mach DOS emulator under a very
non-restrictive license, thanks to which we can legally recycle their
code.  I have kept the original copyright notices in the relevant
files, and also reproduce it here:

     Copyright (c) 1991 Carnegie Mellon University
     All Rights Reserved.

     Permission to use, copy, modify and distribute this software and its
     documentation is hereby granted, provided that both the copyright
     notice and this permission notice appear in all copies of the
     software, derivative works or modified versions, and any portions
     thereof, and that both notices appear in supporting documentation.

     CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
     CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND
     FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS
     THIS SOFTWARE.

     Carnegie Mellon requests users of this software to return to

      Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
      School of Computer Science
      Carnegie Mellon University
      Pittsburgh PA 15213-3890

     any improvements or extensions that they make and grant Carnegie Mellon
     the rights to redistribute these changes.

Porting to 386BSD
=================

   Ha ha ha ha ha ha ha ha ha ha ha hooooooooooooooo ha ha ha ha ha ha
ha ha ha ha ha ha ...

   Oh, wow.  That's a sweet one.  (You can quote me on the above).

   People do occasionally ask about just that: porting dosemu to
386BSD.  I wouldn't mind helping someone port dosemu, but she had
better be clever and committed.  Just in case someone's game, here is a
list of the Linux dependencies:

   * Virtual Console control.  mostly in `termio.c' and `video.c'.

   * Unprocessed scancodes from a TTY.  mostly in `termio.c'

   * the method of accessing video card memory (`mmap' of `/dev/kmem')
     assumes that the lower megabyte of kernel memory is
     identity-mapped.

   * EMS assumes a particular way of sharing pages within a process's
     address space.  There is probably an easy way of doing this under
     386BSD.

   * The emulator-code loader assumes the Linux shared library scheme.

   * the `vm86()' system call and signal semantics.  This is the biggie.

   All in all, a better idea is to port the Mach DOS emulator.  I heard
from some people doing this a while back, but they've been quiet for a
while.  This could mean that they're busy, or dead.

Contribution
============

   If you see some area of dosemu that is incomplete, buggy, or
altogether nonexistent, and you feel halfway competent to do something
about it, *please* consider helping me out by volunteering to work on
that area.  There's so much to do that I can't do it all by myself.
Lately it seems like I can't do *any* of it by myself.

   Seriously, I know most of you use Linux to get away from MS-DOS, but
dosemu can help us get away from MS-DOS but still use those
indispensible programs.  If you have something to offer, not matter how
large or small, please *please* *please* contribute!

   I will maintain a list of people and their projects in this document.
The current list is shown below.

   - gt8134b@prism.gatech.edu -- HOWLIN' BOB
     dosemu in general, the big picture, the whole enchilada, the buck
     stops here; integration of various charity work done by others;
     documentation.  For the moment, I consider this guy the main dosemu
     developer/coordinator.
     Status: needs to be trashed (1).

   - jmaclean@fox.nstn.ns.ca -- JAMES MACLEAN
     smart (non-BIOS) VGA graphics support; the save/restore routines
     which support BIOS-driven video
     Status: Fully functional for non-SVGA modes and integrated into
     dosemu.  SVGA drivers for Trident and ET4000 under development.

   - tridge@nimbus.anu.edu.au -- ANDREW TRIDGELL
     porting and enhancing the redirector from Mach's DOS emulator.
     Also some changes to the scrolling functions of the emulator
     proper, the anti-keyboard-polling mechanism tuned by the
     HogThreshold directive (see Run-time Configuration), and the
     int2f "give up time slice" discovery (2).
     Status: Fully functional and integrated into dosemu.  Waged in a
     neverending war with the DOS "network redirector" kludge.
     Currently working with Stephen Tweedie to correct inconsistencies
     between MS-DOS and DR-DOS.

   This table is here not only as a recognition of their work, and not
only as a guide to who's doing what, and not only as filler...wait,
maybe it *was* here only as filler.

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

   (1)  dosemu, not the author--the author does not indulge.

   (2)  For those of us who wish to multitask under Linux while running
dosemu, the latter two are a big win in CPU savings.

Thanks
======

   * Thanks to Matthias Lautner, the true and original author of dosemu.
     If he hadn't done it first, I wouldn't be doing it now.

   * I can't thank Andrew Tridgell enough for his first class work on
     the redirector.

   * ...or James MacLean for the (S)VGA screeen save/restore routines.
     Without these, graphics under dosemu would be practically unusable.

   * Thanks to *all* those who sent in patches and suggestions; there
     were some *very* helpful people.

   * Thanks to Krishna Balasubramanian for his excellent SYSV IPC
     implementation.  (Not only because dosemu uses SYSV shared memory,
     but because I learned enough from reading his `shm.c' to write the
     `mmap()' modifications that EMS support needed).

   * Thanks to Adam Goldberg for practical advice and sending me the
     XMS 3.0 spec.

   * Thanks to Michael K. Johnson for early encouragement and advice.

   * Thanks to Dennis Marer for sending me spec. sheets (which I still
     haven't gotten around to using!  Hardware emulation WILL happen
     one day).

   * Thanks to Darren Senn for loaning me his EGA/VGA reference book

   * Thanks to Stephen Tweedie for ideas and feedback, and especially
     for helping with the disk redirector.

   * And, of course, thanks to Linus Torvalds for creating the Linux
     miracle!

Installation
************

   While *tsx-11.mit.edu* is the home of dosemu, you should be able to
find dosemu on almost any Linux ftp site.  These are the ones with
which I am familiar:

*tsx-11.mit.edu*
     /pub/linux/ALPHA/dosemu

*sunsite.unc.edu*
     /pub/Linux/system/Emulators/dosemu

*nic.funet.fi*
     /pub/OS/Linux/BETA/dosemu

*wuarchive.wustl.edu*
     /mirrors/linux/??

   The final release version of dosemu 0.49 will be called
`dosemu0.49.tgz' and will be placed in the dosemu directory on
*tsx-11.mit.edu*.

   After you've gotten dosemu, but before you boot MS-DOS, there are
some things you'll need to do.

   * edit the Makefile to suit your system (see README, and below).

   * edit `/etc/dosemu/config' to give it your disk setup (and whatever
     other parameters you feel like changing).  See Run-time Configuration.

   * Compile it.  `make config; make dep; make clean; make install'
     does it best.  If you have gcc earlier than 2.3.3, edit the
     Makefile to give the path to your shared library stubs.

   * Make sure your termcap entries have these fields describing
     keyboard strings:

    `kI'
          Insert

    `kD'
          Delete

    `kh'
          Home

    `kH'
          End

    `ku'
          Up arrow

    `kd'
          Down arrow

    `kr'
          Right Arrow

    `kl'
          Left arrow

    `kP'
          Page Up

    `kN'
          Page Down

    `k1 ... k0'
          Function keys F1 ... F10

     And these fields describing output control sequences:

    `cl'
          Clear screen

    `cm'
          Cursor motion

    `mr'
          Enter reverse video

    `md'
          Enter double bright

    `so'
          Enter standout mode

    `se'
          Leave standout mode

    `me'
          Turn off all appearance modes

    `vi'
          Hide cursor

    `ve'
          Return cursor to normal

     Some of the output control sequences can safely go undefined, such
     as `vi' and `ve'.

     I'm still trying to devise a way to map a variety of foreground and
     background colors, as well as high intensity, onto a very few
     termcap attributes.  Some kind soul produced patches to dosemu
     0.48pl1 and color xterm that allow the use of full color.  I doubt
     I will integrate those patches, instead choosing to incorporate the
     `xdosemu' display mechanism, but I can't give an estimate about
     when that will happen.  Either way, you're free to use the patches
     if they're updated for dosemu 0.49.

   * I recommend that you use libc.so.4.2 or newer.  [However, I
     recommend you NOT use libc.so.4.3, but use libc.so.4.3.2 or newer.
     libc.so.4.3 apparently has some reentrancy problems which can be
     exacerbated by signals, and dosemu LOVES signals...I am using
     4.3.2 with no problems (yet)]

   * If you plan to use raw console video (-c), make a kernel or LILO
     image spec. that will boot into an 80 column mode.  Although it
     isn't overpolished yet, raw console video mode is nice.  You get
     colors and the DOS character set.  Highly recommended if you don't
     mind 80 column console screens.  If you have a monochrome video
     card, change the define in Makefile.  Actually, you can use dosemu
     with other than 80x25 screen sizes; see VGA.

   * If you want to directly access or boot from a DOS hard disk
     partition, you may need to tell dosemu about your hard disk
     geometry by adding an entry to the configuration file.  See Hard Disks,
     and Run-time Configuration, for more info.

     A safer route is to use the MFS redirector to access a Linux
     directory as a DOS network filesystem.  See Disk Redirector,
     for more info.

     You can also use `diskimage' and `hdimage', and a `ramdrive.sys'
     created ramdisk, which runs in XMS or EMS memory!  See Disk Images,
     see Memory, for more info.

     *NOTE:* I have had problems when using an EMS-based ramdrive in
     conjunction with pkzip 2.04e.  This is probably a bug in my code.
     So, if you want to use RAMDRIVE, I recommend you set it up in XMS
     memory (which is probably faster anyway).

   Many thanks to Andrew Tridgell (`tridge@nimbus.anu.edu.au') for
porting the Mach DOS emulator's redirector, and for other tips/fixes as
well.  See Mach

General Info
============

   Here is what you see if you type "dos -?":

     usage: dos [-ACfckbVtsgxKm234] [-D flags] [-M SIZE] [-P FILE]
     [-H|F #disks] > doserr
         -A boot from first defined floppy disk (A)
         -C boot from first defined hard disk (C)
         -f flip definitions for A: and B: floppies
         -c use PC console video (!%)
         -k use PC console keyboard  (!)
         -D set debug-msg mask to flags (+-)(avkdRWspwgxhi01)
         -M set memory size to SIZE kilobytes (!)
         -P copy debugging output to FILE
         -b map VGA BIOS into emulator RAM (%)
         -H specify number of hard disks (1 or 2)
         -F specify number of floppy disks (1-4)
         -V use the BIOS VGA "emulation" (implies -c and -b)
         -N No boot of DOS
         -t deliver time interrupt 9
         -s try new screen size code (COMPLETELY BROKEN)(#)
         -x <SIZE> enable XMS with SIZE kilobytes
         -e <SIZE> enable EMS with SIZE kilobytes (!)
         -2,3,4 choose 286, 386 or 486 CPU
         -K Do int9 within PollKeyboard (!#)

          (!) means BE CAREFUL! READ THE DOCS FIRST!
          (%) marks those options which require dos be run as root (i.e. suid)
          (#) marks options which do not fully work yet

   The invocation I use under an 80x25 console (when not debugging) is
this:

         dos -Vcbkx 4096 -P /dev/tty8 -D0 > dbg

   Under an xterm (1) :

         dos -b -P /dev/tty8 > dbg

   You *must* have any required disk image files in the current
directory! This includes `diskimage' and `hdimage'.  You can, of
course, use symlinks instead.

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

   (1)  I recommend that you resize the xterm to 25 lines first. The
standard 24 is insufficient.  Larger sizes will have no additional
effect.

Updating from 0.48pl1
=====================

   This is a summary of the 0.48pl1 -> 0.49 changes *that affect
configuration or setup*.  See Changes, for a complete list of
changes to dosemu.

   * The format of hdimage has changed; you must add a 128-byte header
     to any hdimage you used in 0.48pl1.  Use the "mkhdimage" command
     to create the appropriate header.  You pass as its arguments the
     geometry of the hdimage file.  For example, if you use the default
     hdmage size, this sequence of commands would work:

          mv hdimage hdimage.old
          mkhdimage -h 4 -s 17 -c 40 | cat - hdimage.old > hdimage

     If you use the default hdimage size, "make convhd" may or may not
     do this for you.  You're probably better off doing it by hand.

   * You can now use direct *partition* access instead of direct *disk*
     access.  See Hard Disks, for information on this.

   * The disk redirector has changed.  You need to discard `linux.exe'
     and replace it with a new program, `emufs.sys'.  `linux.exe' will
     no longer work, and might cause unpredictable results.  See Disk Redirector
     for more information on this.

   * The `Makefile' configuration has changed.  Allmost all
     configuration has been moved into the run-time configuration file
     `/etc/dosemu/config'.  See Configuration, for more details on
     configuring dosemu.

   * dosemu 0.49 requires 0.99pl7 kernels or newer with certain patches
     applied. See Configuration for more details.

   * A BIOS-driven VGA graphics mode has been added. See VGA, for
     more details on graphics under dosemu.

   * the `exitemu.com' program has changed.  Discard any old copies, as
     they will no longer work.

   * See General Info, and Changes, to see what the new
     dosemu options are.  In particular, -e and -x have changed.

Configuration
*************

   This chapter tells about configuration of Linux dosemu.

Requirements
============

   These are the requirements for running dosemu 0.49.

   * dosemu 0.49 requires that you run one of these kernel
     configurations:

        - Linux version 0.99pl7 or 0.99pl7A with `ipcdelta' and
          `mmap.diff' patches applied (1).

        - Linux version 0.99pl8 with `ipcdelta' (2), `ALPHA-diff', and
          `mmap.diff' patches applied.

        - Linux version 0.99pl9 or later with the `ipcdelta' and
          `mmap.diff' patches applied.

   * gcc 2.2.2d7 or newer to compile dosemu

   * libc 4.2 or newer, excepting libc 4.3 because of reentrancy
     problems.  libc 4.3.2 and libc 4.3.3 are fine.

   * a copy of MS-DOS versions 3.3-6.0.  MS-DOS 6.0 compatibility was
     recently added to the disk redirector and has not been thoroughly
     tested.  The author uses MS-DOS 5.0, so versions other than that
     may show imcompatibilities with some areas of dosemu.

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

   (1)  If you will not use EMS emulation, then this patch is not
necessary for any of the kernel versions

   (2)  The ipcdelta patches do not patch cleanly into kernels later
than 0.99pl7.  You'll need to manually edit two files,
`linux/kernel/sys.c' and `linux/kernel/fork.c'.  Hopefully an ipcgamma
set of patches for a later kernel will be released soon.

Compile-time Configuration
==========================

   At present, very little of dosemu is compile-time configured; that
is, a very few of the dosemu configuration options require that you
recompile dosemu for your changes to take effect.  The basic sequence of
events is this:

  1. Edit the `Makefile' to reflect the configuration you desire

  2. Create a new configuration file `config.h' by typing the command
     `make config'

  3. re- make and install the emulator with the commands
          make clean ; make dep ; make config ; make install

   However, most of dosemu's configuration is effected through a file
which dosemu parses at run-time, `/etc/dosemu/config'.  See Run-time Configuration,
for more information.

   Here is a list of the variables you may set in `Makefile':

`KEYBOARD'
     what nationality your keyboard is

Run-time Configuration
======================

   Unlike previous versions, which were configured primarily through
compile-time preprocessor directives speified in the Makefile, dosemu
version 0.49 receives most of its configuration information through a
run-time-parsed plaintext configuration file, usually kept in
`/etc/dosemu/config'.

   The configuration file is made up of a series of "statements"
separated by whitespace.  A statement is composed of one or more
"words", which is a one or more characters bounded by whitespace.  A
statement has a property called "type", which can be one of the
following:

*predicate*
     a single word which specifies a boolean condition (on/off or
     true/false)

*value*
     a word which has one or more "arguments", which appear after it.
     This usually sets some parameter of dosemu's operation.

*list*
     a word which begins a bracket-enclosed list of other statements.
     This is used to group related statements, like the many parameters
     for a single disk.

*comment*
     A comment is ignored.  These are the comment formats:
     Anything between the C-language comment strings /* and */
     Anything from one of the characters `#' or `;' until the end of
     the line.
     The C-like comment delimiters must be separated by whitespace.

   dosemu's config file parser is not case-sensitive.  That is, words
are not differentiated by capitalization.  However, certain *arguments*
may be case-sensitive, like the filename given to the disk config and
printer options; this is a function of how the arguments are used.  It
never hurts to keep things exact, so when in doubt ...

   Here is a list of all the simple statements, their types, and any
arguments.  NOTE: none of these work yet; rely on the compile-time
configuration information.

 - Predicate: bootA
 - Predicate: bootC
     Specifies which disk to boot from; the default is C

 - Value: cpu MODEL
     MODEL can be 80286, 80386, or 80486.  Alternately, you can simply
     specify the X in 80x86.  Specifies the type of CPU EFLAGS
     emulation desired.  See CPU type.

 - Value: DebugFlags FLAGS
     sets the debugging flag set to FLAGS.  See Debugging Messages.

 - Value: HogThreshold USECS
     The minimum number of microseconds (millionths of a second) which
     must pass between int16 keyboard requests for a program to *not* be
     considered a keyboard hog.  Defaults to 20000.  You may wish to
     raise this number if the CPU usage of dosemu is too high; however,
     too high a number will result in poor program performance.

 - Boolean: Keybint FLAG
     Specifies whether the keyboard interrupt 9 will be delivered.
     Default off.

 - Boolean: FastFloppy FLAG
     If FLAG equals "on", dosemu will use a faster, but more
     unreliable, method of accessing real floppy disk drives.  If this
     directive is specified, it may not be safe to remove a floppy disk
     from the drive until at least 5 seconds have passed from the last
     access.  Turning this feature off will make floppy access safer at
     a great expense in speed.  Default on.

 - Boolean: MathCO FLAG
     If the argument is a true synonym (yes, on, 1), then the int15h
     configuration information word will flag the existence of a math
     coprocessor.

 - List: Ports LIST
     Enables dosemu access to the ports specified within list.  A port
     is expressed as a decimal or hexadecimal number; decimal is
     assumed unless the number is prefixed with the C-style `0x'.  A
     range of ports may be specified by `range' BEGIN END, where BEGIN
     is the first port, and END is the last.  This example enables
     access to I/O ports 0x42, 0x61, and 0x300-0x310:
          ports { 0x42 0x61 range 0x300 0x310 }

 - Value: Speaker MODE
     MODE can be one of three values:
    *off*
          no sound at all

    *on*
    *native*
          Allows access to I/O addresses 0x42 and 0x61.  This may or
          may not be dangerous.  It is definitely a bad idea for
          non-console access.

    *emulated*
          Sends an ASCII BEL (7) to the tty when a DOS program
          generates sound.  No attempt is made with the current
          emulation to match the BEL pattern to what native access
          would sound like.  This may change.

 - Predicate: RawKeyboard
     If specified, dosemu will attempt to use RAW keyboard mode.

 - Value: Timer FREQUENCY
     Specifies the frequency of timer ticks in hertz.  Default is 18.2.
     This is a debugging aid; dosemu will eventually deduce the
     requested rate from the virtual timer settings.

 - Boolean: Timint FLAG
     Specifies whether the timer interrupt 8 will be delivered.
     Default on.

     *NOTE:* the current implementation of the timer interrupt is tied
     in with the periodic screen-refresh code.  If you are not using
     console video, setting this value any higher than 18 is a bad
     idea.  In fact, if your screen is refreshing too quickly, try this
     with a lower number.

   See Disk Configuration, for more information about configuring
dosemu's disks.

   See Memory Configuration, for information about configuring
dosemu's memory management.

   See Printers, for more information about configuring dosemu's
virtual printers.

   See Serial Ports, for more information about configuring
dosemu's virtual serial ports.

   See Video Configuration, for more information about configuring
dosemu's display.

   For the words which configure one of a series of objects--which
includes hard disks, floppy disks, and printers--the order in which you
specify the separate devices is vital.  The first disk list specified
configures the first hard disk, the next configures the second hard
disk; configuration works similarly for floppy disks and printers.  So,
put the configuration entries for each category of device in the order
you wish them to appear to DOS.

   This is a sample /etc/dosemu/config file:

     # Linux dosemu 0.49 configuration file
     # Robert Sanders, gt8134b@prism.gatech.edu, 5/16/93
     #

     # debug +Iv-dkmx
     # "debug -a" turns all messages off, used when I'm not debugging.
     debug -a

     # NOTE: you will not be able to share the mouse with XFree86 because
     # the mouse-sharing features of dosemu are broken!

     serial { device /dev/cua0 }
     serial { device /dev/cua1 }

     # These two are set to the defaults.  keybint is still unstable,
     # and timint is necessary for many programs.  These are mostly
     # useful as debugging aids.

     keybint off
     timint on

     # these are all the different video configurations I use for testing
     # the last one is the one I use the most

     # video { vga console graphics vbios_mmap }
     # video { vga console graphics  vbios_file /etc/dosemu/vbios }
     # video {  vga console }
     video { vga console graphics chipset et4000 memsize 1024 vbios_mmap }

     # if you have an ATI VGA Wonder card, uncomment the next line
     # ports { 0x1ce 0x1cf }

     RawKeyboard         # don't include this if you don't want it
     mathco on           # on or off
     cpu 80486           # or 80286 or 80386
     bootC               # or bootA
     xms 1000            # XMS size in K, or off
     ems off             # EMS size in K, or off
     dosmem 640
     fastfloppy on       # set to off for safer but much slower floppies

     ports { 0x388 0x389 }  # for SimEarth
     speaker native         # also off or emulated

     #******************* HARD DISKS *******************************
     disk { image "hdimage" }
     disk { partition "/dev/hda1" 1 }        # 1st partition on 1st disk

     #******************* FLOPPY DISKS *****************************
     floppy { device /dev/fd0 fiveinch }
     floppy { device /dev/fd1 threeinch }

     printer { options "%s" command "lpr" timeout 20 }
     printer { options "-p %s" command "lpr" timeout 10 }    # pr format it

   Use the supplied program `/etc/dosemu/mkpartition' to set up the
appropriate other files in /etc/dosemu.  See Hard Disks, for more
details.

Running dosemu
**************

Booting
=======

   To boot dosemu for the first time, all you need do is this:

  1. Create a bootable disk under real MS-DOS and put these programs on
     it:

        * fdisk

        * format

        * sys

        * command.com

     Then, enter Linux and create a `diskimage' file from that boot.
     See Creating diskimage.

  2. Boot dosemu from the `diskimage' file:
          dos -A > dosdbg

     The dosdbg file holds dosemu's diagnostic debugging messages.
     See Debugging Messages

   Now you've booted.  If you wish, you may go on to create a hdimage
file.

  1. Run fdisk.  Make sure that the first disk has a primary partition.
     See `The DOS Reference Manual' for more information about using
     fdisk.

  2. Exit dosemu and then reboot (as in step 2 above).  See Exiting.

  3. If the hdimage does not already have a DOS filesystem on it,
     create one with this line:
          format c:
     Make sure that it is bootable with these commands:
          sys c:
          c:

  4. Exit dosemu.  You should now be able to invoke dosemu with the `-C'
     option to boot from hard disk.

   You may boot DOS under dosemu from any of these disk devices:

   * A floppy image (`diskimage').  See Creating diskimage

   * A hard drive image (`hdimage').  See Creating hdimage

   * A real floppy drive.  See Configuration

   * A real direct-accessed DOS hard drive (both SPA and WDA).  See
     Hard Disks.

Exiting
=======

   To kill the dos emulator, execute the EXITEMU.COM file found on the
included hdimage, or send a `SIGTERM' or `SIGHUP' signal to it, or in
RAW keyboard mode, type `ctrl-alt-pgdn'.  If you need to simulate a
ctrl-break in the emulator, you can send it a `SIGQUIT' from somewhere
else. (Of course, in RAW keyboard mode, `ctrl-break' does what it's
supposed to).

   Send a `SIGKILL' to the emulator only as a last resort.  This will
not allow the emulator to restore the state of the tty, restore the
state of the screen, or flush all open files, including the debugging
file.  Use `SIGTERM' or `SIGHUP' instead, if at all possible.

Debugging Messages
==================

   The emulator, being so early *alpha*, has a considerable amount of
code dedicated to debugging itself.  The most noticeable effect of all
this code is the plethora of debugging messages printed to stdout.  Some
classes of messages are printed out, while others are suppressed.  You,
the intrepid user, can choose which classes of debugging messages are
suppressed.

   Dosemu takes an option `-D' FLAGS, where FLAGS is a string of
letters which specify which options to print or suppress.  Dosemu parses
this string from left to right.  You may also set the debugging flags
in the run-time configuration file.  See Run-time Configuration.

`+'
     turns the following options on;  if the debug level is 0, sets it
     to 1.  otherwise, leaves it the same.  the initial state is +
     (level = 1).

`-'
     turns the following options off (sets debug level to 0)

`a'
     turns all the options on/off, depending on whether +/- is set

`0...9'
     sets the debug level.  0 is off (same effect as `-', 1 is the
     least verbose level, 9 is the most verbose level)

`$'
     where $ is a letter from the valid class list (see below), turns
     that option off/on depending on the debug level.

   Debugging message classes:

        d   disk            v   video          R   disk Reads
        k   keyboard        i   port I/O       W   disk Writes
        s   serial          p   printer        h   hardware
        w   warnings        g   general        x   XMS
        m   mouse           I   IPC            E   EMS
        c   configuration

   Any debugging classes following a "+" character, up to a "-"
character, will be turned on (non-suppressed).  Any after a "-"
character, up to a "+" character, will be suppressed.  The character
"a" acts like a string of all possible debugging classes, so "+a" turns
on all debugging messages, and "-a" turns off all debugging messages.
The characters "0" and "1" are also special: "0" turns off all
debugging messages, and "1" turns on all debugging messages.

   There is an assumed "+" at the beginning of the FLAGS string.  Some
classes, such as error, can not be turned off.  You must tolerate
these; you could always redirect stdout to /dev/null if you REALLY
don't want them.

   Some examples:

`-D-a'
     turn off all messages (except errors)

`-D+a-v'
`-D1-v'
     turn on all debugging messages but video

`-D+kd'
     turn on keyboard and disk messages; other options are left at the
     default.

`-D-a+RW'
     turn on only disk READ and WRITE messages

   Any option letter can occur in any place.  Even pointless
combinations, such as "-D01-a-1+0", will be parsed without error, so be
careful.  Some options are set by default, some are clear. This is
subject to my whim, and will probably change between releases.  You can
ensure which are set by always explicitly specifying them.

Input/Output
************

   This is the section dealing with the various ways dosemu gets its
info to you.

Keyboard
========

   When dosemu uses RAW keyboard on the Linux console, it causes the
kernel to pass every key scancode directly to the emulator's stdin
without performing any interpretation or translation.  Therefore, it is
the emulator's responsibility to translate key positions into ASCII
codes.

   The current emulator has perfect support for only the US keyboard.
Some foreign keyboards which do not depend on dead keys/diacriticals
will also work.

   You may select the keyboard you wish to use in the same way you would
select it for the kernel: edit the Makefile so that you have only one
"KEYBOARD=" line uncommented.  The default setup is a U.S. keyboard.

   In RAW keyboard mode, VC switching is accomplished by using
`LeftAlt-Fn', where `RightAlt-Fn' gives you an alt-functionkey as in
normal DOS.  Otherwise, almost any key combination should act exactly
as it would under native DOS. (write me if it doesn't)

   XFree86 1.2 uses `ctrl-alt-Fn' to switch between consoles. Bother.
If you want this, write me, and I'll think about it.

   Some special keys under RAW keyboard mode:

`ctrl-scrlock'
     shows the first 0x32 int vectors on debug output

`alt-scrlock'
     show the vm86 registers

`rshift-scrlock'
     generate an int8 (timer tick)

`lshift-scrlock'
     generate an int9 (keyboard service)

`ctrl-break'
     ctrl-break as under DOS.

`ctrl-alt-pgup'
     reboot DOS. imperfectly done. don't trust this.

`ctrl-alt-pgdn'
     exit the emulator (same as using EXITEMU.COM)

`pause'
     pause/unpause dosemu.  Extremely useful.

   (most of these are useful for debugging purposes only)

   I chose not to use `ctrl-alt-del' to reboot dosemu because it's a bad
habit to get into.  I accidentally rebooted my machine a couple of
times, and decided that authenticity was somewhat less important than
safety.

   If you're using an unstable version of dosemu like one of the test
releases, then you might wish to manually insert this patch into your
linux kernel source.

   file: `linux/kernel/chr_drv/keyboard.c' line: approximately line 103
in kernel version 0.99pl7a

             if (vc_kbd_flag(kbd,VC_RAW)) {
                     kbd_flags = 0;
     +               if (scancode == 0x54) clr_vc_kbd_flag(kbd,VC_RAW);
                     put_queue(scancode);
                     goto end_kbd_intr;
             }
     +       else if (scancode == 0x54) set_vc_kbd_flag(kbd,VC_RAW);
             if (scancode == 0xe0) {
                     set_kbd_dead(KGD_E0);
                     goto end_kbd_intr;

   This rather crudely redefines the `SysRq' key, generated by pressing
`RightAlt-PrintScreen', to toggle the `RAW' keyboard state.  If you are
using dosemu in `RAW' console keyboard mode, then this patch can be
used to restore your keyboard's sanity after a nasty dosemu crash.  I
have to use this very infrequently when testing serious dosemu changes,
and never with a "production" version of dosemu.

   Once again, I recommend you NOT use the -k (raw console keyboard)
option unless you really need it or are sure you can handle the risks,
and that if you do, you apply the kernel patch listed above.  If the
emulator crashes (as it so rarely does :-), you might be left in
suspended animation.  You can now exit DOS with CTRL-ALT-PGDN , so
you'll most likely not get stuck.  However, a REALLY serious crash might
leave the keyboard in RAW mode, and then, unless you applied my tiny
patch, you really are stuck.  Since I made the keyboard code safer (in
0.47.7), I've had this happen ONCE, and that was caused by what I
suspect to be a kernel bug.  So you're probably safe.

   Also, the multinational support with RAW keyboard mode is very
sketchy.  I have the keyboard types selectable in the Makefile (like
the kernel does), but I for some reason removed the deadkey/diacritical
code when I first implemented RAW mode (my scancode parsing code is
lifted wholesale from the kernel.  Thanks, Linus! :-)  I dunno why.
Anyway, until I put it back in, you foreigners are probably
disadvantaged.  And the DOS "keyb" command crashes the emulator, so
don't get any ideas. :-)

   Could someone who *uses* diacriticals write me to confirm this?  Do
I need to do it, or can I put it at the bottom of my TODO list?

   You'll need to use RAW keyboard mode to run WordPerfect, as it uses
all sorts of godawful ctrl/alt-fkeys.  I'm thinking of ways to support
these sorts of combinations without RAW keyboard mode, but nothing
really seems "transparent" enough yet.

Console Video
=============

   Hmmm.  This is one of the first features I added to the DOS emulator,
and I find it one of the most useful.  Basically, when you enable
console video by giving dosemu the "-c" flag, dosemu bypasses the whole
tty universe and writes directly to video RAM.

   The advantages:
   * very fast

   * you get color and PC graphics characters

   The disadvantages:
   * still doesn't support screen widths greater than 80 characters

   * only works on the console (i.e. not over a serial line, not over a
     network)

   With XFree86 1.2 you have the ability to switch virtual consoles
even while running an X session.  So, the best environment for X users
is probably to boot Linux into an 80x25 screen size, run dosemu on one
VC, and run XFree86 1.2 on another.

   Just in case you're wondering, and because someone asked, if you want
to start dosemu from a console, say 1, and run it on another console,
say 7, you'd do it like this (add your own favorite options):

             dos -ck > dosdebug </dev/tty7  2>/dev/tty7 &

   For those of you who like text screen sizes other than 80x25, I
apologize.  I am working on support for these, but it hasn't seemed
urgent, so it hasn't gotten done.  The present way to coerce dosemu into
using a screen size other than 80x25 is to use the BIOS-driven video
emulation along with some ANSI.SYS or replacement driver.  After
booting dosemu, you'll have to run some program to set the screen size
to the desired mode, as the video card initialization will put dosemu
into 80x25 test mode.  See VGA.

   If you don't use console video, dosemu reverts to the old method of
screen refresh, which is to translate the DOS virtual-screen memory
into a normal stream of ASCII characters and terminal control sequences
(read from your /etc/termcap).  This method is much slower, doesn't
support color, and doesn't support most of the PC graphics characters.
However, you can use this in an xterm or over a serial line.

   There is a modified DOS emulator (xdosemu) whose display routines are
based upon color xterm.  xdosemu runs in its own native X window.  It
supports color, enhanced keyboard (like my "-k" RAW keyboard mode), most
PC graphics characters, and its output should be faster than my dosemu's
termcap output to an xterm.  The newest version (xdosemu 0.3) has many
of dosemu 0.48pl1's features, so by all means give it a try.

   You can get it on tsx-11.mit.edu as
/pub/linux/ALPHA/dosemu/xdos03.tgz (it is a tar'ed and gzip'ed file).

   In addition, I will one day incorporate some form of X support,
whether it is taken from xdosemu or not.

VGA
===

   Well, it isn't what I wanted, but it's something.  Dosemu 0.49 can
now run your video card's native BIOS within a dosemu session to provide
VGA compatibility (1).

   The simplest way of enabling this cheap emulation is to specify the
`-V' option on the dosemu command line, or to specify the proper
configuration words in the run-time configuration file.  See General Info,
for more information on command-line options.  See Run-time Configuration,
for more information about the configuration file.

   These methods initialize the video card's BIOS by enabling the full
range of video I/O ports and making a far call to the standard address
of a video card's initialization routine (c000:0003).  The video card
should show its banner, then return to the DOS boot sequence.

   You must enable graphics in this way if you wish to use another video
driver such as ANSI.SYS.

   To return to normal mode, run `vgaoff.com'.  This simply turns off
I/O permissions and revectors the int10h vector to the normal dosemu
routine.

   This is a list of programs I've tried with some or full success:

   * tlivesa.com, a VESA extender for ET4000 cards

   * dosshell in ALL the video modes, graphics and text.

   * WordPerfect 5.0 page-preview with the driver set to IBM 640X480
     VGA.

   * Picture viewers:
    *dvpeg*
    *jpg_menu*
          JPEG & GIF viewers.  Both of these detected and used the
          15-bit HiColor capabilities of my ET4000 card.

    *cview*
          JPEG & GIF viewer.  requires `tlivesa.com'; also utilized the
          15- and 16- bit HiColor modes.

    *cshow*
          the standard CompuServe GIF viewer

   * galactix.  This is your standard arcade game.  Run this with the
     `-t' command-line option and the speaker ports enabled.

   * F19, a flight simulator

   * SimEarth (2)

   * SimCity

   * Flight Simulator (with some keyboard hacks not fully implemented
     yet)

   * Windows 3.0 in real mode (with a lot of hacks not fully
     implemented yet)

   * fractint (using `tlivesa' for the 1024x768x256c mode)

   * dmode and vmodeb; these are mode switchers for the ET4000.  dmode
     can also be used to set certain operational parameters of the
     video card, such as default refresh rates for a given video mode.

   * norton utilities in graphics mode; the text mode also ran better
     with VGA on.

   * Scorched Earth, a video game

   If you try it out, please send me what programs you got it to work
with, what modes worked, and how well.

   You may choose BIOS-driven graphics through the configuration file
with a directive like `video { vga console graphics }'.  See Video Configuration.

   If a program crashes and leaves you screen in an indeterminate state,
simply exit dosemu, boot a new one, and run `vgaon.com'.  This will
re-initialize your video card to its bootup state.

   You can now switch virtual consoles when in BIOS VGA mode, with some
restrictions.  SuperVGA modes are only partially supported, and are not
yet recommended for use.

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

   (1)  It should be possible to implement CGA/EGA/MDA compatibility
also, but there are added difficulties.  Contact me if you are
interested.

   (2)  Give dosemu access to the ports 0x388 and 0x389 if you wish to
run SimEarth.  I don't know what these ports do or I would have dosemu
emulate them.