\input texinfo    @c -*-texinfo-*- 
@comment %**start of header
@setfilename dosemu.info
@settitle Dosemu v@value{emuver}
@setchapternewpage odd
@comment %**end of header

@c $Author: root $
@c $Date: 1994/06/12 23:17:14 $
@c $Source: /home/src/dosemu0.60/doc/RCS/dosemu.texinfo,v $
@c $Revision: 2.1 $
@c $State: Exp $


@set emuver 0.49
@set docver 1
@set printdate @today{}
@set reldate May 1993

@ifinfo
This file documents the Linux MS-DOS emulator version @value{emuver}.

Copyright @copyright{} 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).
@end ifinfo

@titlepage
@title DOSEMU
@subtitle The Linux MS-DOS Emulator Manual, Edition @value{docver}
@subtitle for dosemu Version @value{emuver}
@subtitle @value{reldate}

@author by Robert Sanders

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1993 Robert Sanders



This is edition @value{docver} of the DOSEMU documentation; it describes
version @value{emuver} of the Linux MS-DOS emulator.  Any resemblance
herein to persons or places, real or imaginary, is purely coincidental
and most definitely @emph{not} grounds for lawsuits or nastiness of any
other kind directed at the author.



(Un)Published by Robert Sanders@*
38134 GA Tech Station@*
Atlanta, GA  30332@*

Printed on @today{}

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.


Permission is granted to copy and distribute modified versions of this 
manual under the conditions for verbatim copying, provided that the entire 
resulting work is distributed under the terms of a permission notice
identical to this one.


Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by Robert Sanders, his immediate family, or anyone with a
convincingly deep voice.  Said approval must take place on a Tuesday,
sort of middle afternoonish if that's not too much trouble..
@end titlepage

@node  Top, Introductory Stuff  , (dir),  (dir)

@menu
* Introductory Stuff::   abandon all hope ye who enter here
* Installation::         munging your system for fun and profit
* Configuration::        how to set it up
* Running dosemu::
* Input/Output::         how you and dosemu communicate
* Peripherals::          your computer and the outside world
* Memory::               support for crufty DOS Memory Specifications
* Miscellaneous::        just stuff
* Programs That Work::   what works, what doesn't
* Bugs::                 they are legion
* Changes::              my machinations since dosemu 0.48pl1
* Concept Index::
* Program/File Index::
@end menu


@node Introductory Stuff, Installation, top, top
@chapter Introductory Stuff

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

@menu
* Greetings::    
* Mach::
* Porting to 386BSD::
* Contribution::
* Thanks::
@end menu

Let me begin with a general explanation of what exactly dosemu @emph{is},
before I get too bogged down trying to explain what dosemu @emph{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 @dfn{DOS box}.  The DOS box, a combination of hardware and
software trickery, has these capabilities:

@itemize @bullet
@item
the ability to @dfn{virtualize} all input/output and processor control
instructions
@item
the ability to support the word size and addressing modes of the iAPX86
processor family's @dfn{real mode}, while still running within the full
protected mode environment
@item
the ability to trap all DOS and BIOS system calls and emulate such calls
as are necessary for proper operation and good performance
@item
the ability to simulate a hardware environment over which DOS programs are
accustomed to having control.  
@item
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.
@end itemize

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

@cindex Releases
@cindex Timeline
These are the release dates of dosemu:

@table @strong
@item 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.  
@item 0.47
January  27, 1993
@item 0.47.7
February  5, 1993
@item 0.48
February 16, 1993
@item 0.48pl1
February 18, 1993


These versions added console video, raw keyboard, @sc{xms},
timer tick, @sc{vga} attribute fix, simple printer support, @sc{bios}
serial ports, and lots of bug fixes.
@item 0.49
May 20, 1993
The 0.49 release added EMS, a new disk redirector, revamped hard disk
support, a more sophisticated printer driver, @sc{bios}-driven @sc{vga}
support, serial port emulation, keyboard TAMEing, and lots more bug fixes.
@end table


If you need me, you can reach me at these addresses @footnote{Even if
you don't need me, you can...}:

@cindex Author
@cindex e-mail
@display
Internet:  gt8134b@@prism.gatech.edu

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

Enjoy!


@node Greetings, Mach, , Introductory Stuff
@section Greetings
@cindex Greetings
@comment
Hello, public,

This is dosemu version @value{emuver}.  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. @value{emuver}) should be printed on the invocation
screen, in case you forget which version this is.

This is an @sc{alpha} release; dosemu is far from stable.  I do not
expect dosemu to reach @sc{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 @value{emuver} 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.


@node Mach, Porting to 386BSD , Greetings, Introductory Stuff
@section Mach
@cindex Mach
@cindex Mach copyright
@cindex Copyrights
@comment
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 @emph{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:

@table @code
@item mfs.c
@item mfs.h
@item 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).
@item 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.
@item 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 @code{base.h} and
@code{bios.h}
@end table

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:

@display
@group

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.

@end group
@end display

@node Porting to 386BSD, Contribution, Mach, Introductory Stuff
@section Porting to @sc{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 @dots{}

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

People do occasionally ask about just that: porting dosemu to
@sc{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:

@itemize @bullet
@item
Virtual Console control.  mostly in @code{termio.c} and @code{video.c}.
@item
Unprocessed scancodes from a @sc{tty}.  mostly in @code{termio.c}
@item
the method of accessing video card memory (@code{mmap} of
@code{/dev/kmem}) assumes that the lower megabyte of kernel memory is
identity-mapped. 
@item
@sc{ems} assumes a particular way of sharing pages within a process's
address space.  There is probably an easy way of doing this under
@sc{386bsd}.
@item
The emulator-code loader assumes the Linux shared library scheme.
@item
the @code{vm86()} system call and signal semantics.  This is the biggie.
@end itemize


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.


@node Contribution ,Thanks , Porting to 386BSD, Introductory Stuff
@section Contribution
@cindex Contribution
@cindex Authors
@cindex Developers

If you see some area of dosemu that is incomplete, buggy, or altogether
nonexistent, and you feel halfway competent to do something about it,
@emph{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 @emph{any} of it by myself.

Seriously, I know most of you use Linux to get away from @sc{ms-dos},
but dosemu can help us get away from @sc{ms-dos} but still use those
indispensible programs.  If you have something to offer, not matter how
large or small, please @emph{please} @strong{please} contribute!

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

@itemize @minus
@item
gt8134b@@prism.gatech.edu --- @sc{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 @footnote{dosemu, not the author---the
author does not indulge.}.

@ignore
@comment *** These two haven't kept in touch with me, so I have
@comment *** temporarily removed them from the list
@item
iiitac@@pyramid.swansea.ac.uk --- @sc{Alan Cox}@*
Hercules graphics support@*
Status: Working, but not ready to integrate.

@item
bdsgate!martin@@uunet.UU.NET --- @sc{Martin Harriss}@*
Novell network support (a simulated pktipx within dosemu, or some such)@*
Status: very early development, or maybe not.  
@end ignore

@item
jmaclean@@fox.nstn.ns.ca --- @sc{James MacLean}@*
smart (non-@sc{bios}) VGA graphics support; the save/restore routines
which support @sc{bios}-driven video@* 
Status: Fully functional for non-SVGA modes and integrated into dosemu.
SVGA drivers for Trident and ET4000 under development.

@item
tridge@@nimbus.anu.edu.au --- @sc{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
(@xref{Run-time Configuration}), and the int2f "give up time slice"
discovery @footnote{For those of us who wish to multitask under Linux
while running dosemu, the latter two are a big win in CPU savings.}.@* 
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. 
@end itemize

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
@emph{was} here only as filler.


@node Thanks,  , Contribution, Introductory Stuff
@section Thanks
@cindex Thanks

@itemize @bullet
@item
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.
@item
I can't thank Andrew Tridgell enough for his first class work on the
redirector.
@item
...or James MacLean for the (S)VGA screeen save/restore routines.
Without these, graphics under dosemu would be practically unusable.
@item 
Thanks to @emph{all} those who sent in patches and suggestions;
there were some @emph{very} helpful people.
@item
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 @code{shm.c} to write the
@code{mmap()} modifications that EMS support needed).
@item
Thanks to Adam Goldberg for practical advice and sending me the XMS 3.0 spec.
@item 
Thanks to Michael K. Johnson for early encouragement and advice.
@item
Thanks to Dennis Marer for sending me spec. sheets (which I still haven't
gotten around to using!  Hardware emulation WILL happen one day).
@item
Thanks to Darren Senn for loaning me his EGA/VGA reference book
@item
Thanks to Stephen Tweedie for ideas and feedback, and especially for
helping with the disk redirector.
@item
And, of course, thanks to Linus Torvalds for creating the Linux miracle!
@end itemize

@comment **************************************************
@node Installation, Configuration ,Introductory Stuff, top
@chapter Installation
@cindex Installation
@cindex ftp sites
@cindex availibility
@comment

@menu
* General Info::
* Updating from 0.48pl1::
@end menu

While @emph{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:

@table @emph
@item tsx-11.mit.edu
/pub/linux/ALPHA/dosemu
@item sunsite.unc.edu
/pub/Linux/system/Emulators/dosemu
@item nic.funet.fi
/pub/OS/Linux/BETA/dosemu
@item wuarchive.wustl.edu
/mirrors/linux/??
@end table

The final release version of dosemu 0.49 will be called
@code{dosemu0.49.tgz} and will be placed in the dosemu directory on
@emph{tsx-11.mit.edu}.  

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

@itemize @bullet
@item
edit the Makefile to suit your system (see README, and below).

@item
edit @file{/etc/dosemu/config} to give it your disk setup (and whatever
other parameters you feel like changing).  @xref{Run-time Configuration}.

@item
Compile it.  @code{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.  

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

@table @kbd
@item kI
Insert
@item kD
Delete
@item kh
Home
@item kH
End
@item ku
Up arrow
@item kd
Down arrow
@item kr
Right Arrow
@item kl
Left arrow
@item kP
Page Up
@item kN
Page Down
@item k1 @dots{} k0
Function keys F1 @dots{} F10
@end table

And these fields describing output control sequences:

@table @kbd
@item cl
Clear screen
@item cm
Cursor motion
@item mr
Enter reverse video
@item md 
Enter double bright
@item so
Enter standout mode
@item se
Leave standout mode
@item me
Turn off all appearance modes
@item vi
Hide cursor
@item ve
Return cursor to normal
@end table

Some of the output control sequences can safely go undefined, such as
@code{vi} and @code{ve}.

@pindex xdosemu
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
@code{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.

@item
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)]

@item
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; @xref{VGA}.

@item
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.
@xref{Hard Disks}, and @ref{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.  @xref{Disk Redirector}, for more info.

You can also use @code{diskimage} and @code{hdimage}, and a 
@code{ramdrive.sys} created ramdisk, which runs in XMS or EMS memory!  
@xref{Disk Images}, @xref{Memory}, for more info.

@strong{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).
@end itemize

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



@node General Info, Updating from 0.48pl1, , Installation
@section General Info
@cindex General Info
@comment
Here is what you see if you type "dos -?":

@example
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
@end example

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

@example
    dos -Vcbkx 4096 -P /dev/tty8 -D0 > dbg
@end example

Under an xterm @footnote{I recommend that you resize the xterm to 25
lines first. The standard 24 is insufficient.  Larger sizes will have no
additional effect.} :

@example
    dos -b -P /dev/tty8 > dbg
@end example

You @strong{must} have any required disk image files in the current 
directory! This includes @code{diskimage} and @code{hdimage}.  
You can, of course, use symlinks instead.



@comment **************************************************
@node Updating from 0.48pl1, , General Info, Installation
@section Updating from 0.48pl1
@cindex Updating from 0.48pl1
@cindex Changes since 0.48pl1
@cindex new hdimage format

This is a summary of the 0.48pl1 -> 0.49 changes @emph{that affect
configuration or setup}.  @xref{Changes}, for a complete list of changes
to dosemu.

@c 17 4 40, s h c
@pindex mkhdimage
@itemize @bullet
@item
The format of hdimage has changed; you must add a 128-byte header to any
hdimage you used in 0.48pl1.  Use the @dfn{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:

@cindex hdimage
@pindex hdimage
@example
mv hdimage hdimage.old
mkhdimage -h 4 -s 17 -c 40 | cat - hdimage.old > hdimage
@end example 

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.  

@item
You can now use direct @emph{partition} access instead of direct
@emph{disk} access.  @xref{Hard Disks}, for information on this.

@item
@pindex emufs.sys
@pindex linux.exe
The disk redirector has changed.  You need to discard @code{linux.exe}
and replace it with a new program, @code{emufs.sys}.  @code{linux.exe}
will no longer work, and might cause unpredictable results.
@xref{Disk Redirector} for more information on this.

@pindex /etc/dosemu/config
@item
The @code{Makefile} configuration has changed.  Allmost all
configuration has been moved into the run-time configuration file
@file{/etc/dosemu/config}.  @xref{Configuration}, for more details on
configuring dosemu. 

@item
dosemu 0.49 requires 0.99pl7 kernels or newer with certain patches
applied. @xref{Configuration} for more details.

@item
A @sc{bios}-driven VGA graphics mode has been added. @xref{VGA}, for
more details on graphics under dosemu.

@item
the @code{exitemu.com} program has changed.  Discard any old copies, as
they will no longer work.

@item
@xref{General Info}, and @xref{Changes}, to see what the new dosemu
options are.  In particular, -e and -x have changed.
@end itemize


@comment ******************************
@node Configuration, Running dosemu, Installation, top
@chapter Configuration
@cindex Configuration

This chapter tells about configuration of Linux dosemu.

@menu
* Requirements::                    kernels, patches, etc.
* Compile-time Configuration::      hard code it!
* Run-time Configuration::          expermienting with usefulness
@end menu

@node Requirements, Compile-time Configuration, , Configuration
@section Requirements
@cindex Requirements
@cindex Linux version
@cindex Kernel version

These are the requirements for running dosemu @value{emuver}.

@itemize @bullet

@item
dosemu @value{emuver} requires that you run one of these kernel configurations:

@itemize @minus
@pindex mmap
@pindex ipcdelta
@pindex kernel
@item
Linux version 0.99pl7 or 0.99pl7A with @code{ipcdelta} and
@code{mmap.diff} patches applied @footnote{If you will not use EMS
emulation, then this patch is not necessary for any of the kernel
versions}. 

@item 
Linux version 0.99pl8 with @code{ipcdelta} @footnote{The ipcdelta
patches do not patch cleanly into kernels later than 0.99pl7.  You'll
need to manually edit two files, @file{linux/kernel/sys.c} and
@file{linux/kernel/fork.c}.  Hopefully an ipcgamma set of patches for a
later kernel will be released soon.}, @code{ALPHA-diff}, and
@code{mmap.diff} patches applied.

@item 
Linux version 0.99pl9 or later with the @code{ipcdelta} and
@code{mmap.diff} patches applied.  
@end itemize

@item
gcc 2.2.2d7 or newer to compile dosemu

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

@item
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.

@end itemize

@node Compile-time Configuration, Run-time Configuration, Requirements, Configuration
@section Compile-time Configuration
@cindex 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:

@enumerate
@item
Edit the @code{Makefile} to reflect the configuration you desire
@item
Create a new configuration file @code{config.h} by typing the command
@code{make config}
@item
re- make and install the emulator with the commands
@example
make clean ; make dep ; make config ; make install
@end example
@end enumerate

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

Here is a list of the variables you may set in @file{Makefile}:

@table @code
@item KEYBOARD
what nationality your keyboard is
@end table


@node Run-time Configuration, , Compile-time Configuration, Configuration
@section Run-time Configuration
@cindex Run-time Configuration

@pindex /etc/dosemu/config
@pindex mkpartition

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 @file{/etc/dosemu/config}.

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

@table @emph
@item predicate
a single word which specifies a boolean condition (on/off or true/false)
@item value
a word which has one or more @dfn{arguments}, which appear after it.
This usually sets some parameter of dosemu's operation. 
@item 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.
@item comment
A comment is ignored.  These are the comment formats:@*
Anything between the C-language comment strings /* and */@*
Anything from one of the characters @code{#} or @code{;} until the end
of the line. @*
The C-like comment delimiters must be separated by whitespace.

@end table

dosemu's config file parser is not case-sensitive.  That is, words are
not differentiated by capitalization.  However, certain @emph{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 @dots{}


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.


@deffn Predicate bootA
@deffnx Predicate bootC
Specifies which disk to boot from; the default is C
@end deffn

@deffn Value cpu model
@var{model} can be 80286, 80386, or 80486.  Alternately, you can simply
specify the @var{x} in 80x86.  Specifies the type of @sc{cpu eflags}
emulation desired.  @xref{CPU type}. 
@end deffn

@deffn Value DebugFlags flags
sets the debugging flag set to @var{flags}.  @xref{Debugging Messages}.
@end deffn

@deffn Value HogThreshold usecs
The minimum number of microseconds (millionths of a second) which must
pass between int16 keyboard requests for a program to @emph{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.
@end deffn

@deffn Boolean Keybint flag
Specifies whether the keyboard interrupt 9 will be delivered.  Default off.
@end deffn

@deffn Boolean FastFloppy flag
If @var{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.
@end deffn

@deffn 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. 
@end deffn

@deffn 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 @code{0x}.  A range of ports may
be specified by @code{range} @var{begin} @var{end}, where @var{begin} is
the first port, and @var{end} is the last.  This example enables access
to I/O ports 0x42, 0x61, and 0x300--0x310:
@example
ports @{ 0x42 0x61 range 0x300 0x310 @}
@end example
@end deffn

@cindex Speaker
@cindex Sound
@deffn Value Speaker mode
@var{mode} can be one of three values:
@table @strong
@item off
no sound at all
@item on
@itemx 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.
@item 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.
@end table
@end deffn

@deffn Predicate RawKeyboard
If specified, dosemu will attempt to use RAW keyboard mode.
@end deffn

@deffn 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.
@end deffn

@deffn Boolean Timint flag
Specifies whether the timer interrupt 8 will be delivered.  Default on.

@strong{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.
@end deffn

@xref{Disk Configuration}, for more information about configuring
dosemu's disks.

@xref{Memory Configuration}, for information about configuring
dosemu's memory management.

@xref{Printers}, for more information about configuring dosemu's virtual
printers. 

@xref{Serial Ports}, for more information about configuring dosemu's virtual
serial ports. 

@xref{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:

@example
# 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
@end example

@pindex mkpartition
Use the supplied program @code{/etc/dosemu/mkpartition}
to set up the appropriate other files in /etc/dosemu.  @xref{Hard
Disks}, for more details.
@table @code
@end table


@comment **************************************************
@node Running dosemu, Input/Output, Configuration, top
@chapter Running dosemu
@cindex Running dosemu

@menu
* Booting::
* Exiting::
* Debugging Messages::
@end menu

@node Booting, Exiting, , Running dosemu
@section Booting
@comment
To boot dosemu for the first time, all you need do is this:

@enumerate
@item
Create a bootable disk under real MS-DOS and put these programs on it:

@itemize @bullet
@item
fdisk
@item
format
@item
sys
@item
command.com
@end itemize

Then, enter Linux and create a @code{diskimage} file from that boot.
@xref{Creating diskimage}.

@item
Boot dosemu from the @code{diskimage} file:
@example
dos -A > dosdbg
@end example

The dosdbg file holds dosemu's diagnostic debugging messages.
@xref{Debugging Messages}
@end enumerate


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

@enumerate
@item
Run fdisk.  Make sure that the first disk has a primary partition.  See
@cite{The DOS Reference Manual} for more information about using fdisk.

@item
Exit dosemu and then reboot (as in step 2 above).  @xref{Exiting}.

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

@item
Exit dosemu.  You should now be able to invoke dosemu with the @code{-C}
option to boot from hard disk.
@end enumerate


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

@itemize @bullet
@item 
A floppy image (@code{diskimage}).  @xref{Creating diskimage}
@item
A hard drive image (@code{hdimage}).  @xref{Creating hdimage}
@item
A real floppy drive.  @xref{Configuration}
@item
A real direct-accessed DOS hard drive (both SPA and WDA).  @xref{Hard
Disks}. 
@end itemize



@node Exiting, Debugging Messages, Booting, Running dosemu
@section Exiting
@cindex Exiting

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

Send a @code{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 @code{SIGTERM} or @code{SIGHUP} instead, if at all possible.



@node Debugging Messages, , Exiting, Running dosemu
@section Debugging Messages
@cindex Debugging Messages
@comment
The emulator, being so early @emph{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 @code{-D} @var{flags}, where @var{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.  @xref{Run-time Configuration}.

@table @code
@item +
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).
@item -
turns the following options off (sets debug level to 0)
@item a
turns all the options on/off, depending on whether +/- is set
@item 0@dots{}9
sets the debug level.  0 is off (same effect as @code{-}, 1 is the
least verbose level, 9 is the most verbose level)
@item $
where $ is a letter from the valid class list (see below), turns
that option off/on depending on the debug level.
@end table

Debugging message classes:

@example
   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
@end example

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:


@table @code
@item -D-a
turn off all messages (except errors)
@item -D+a-v
@item -D1-v
turn on all debugging messages but video
@item -D+kd
turn on keyboard and disk messages; other options are left at the default.
@item -D-a+RW
turn on only disk READ and WRITE messages
@end table

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.

@node Input/Output, Peripherals, Running dosemu, top
@chapter Input/Output
@cindex Input/Output

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

@menu
* Keyboard::
* Console Video::
* VGA::
* Video Configuration::
@end menu

@node Keyboard, Console Video, , Input/Output
@section Keyboard
@cindex Keyboard
@comment

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
@kbd{LeftAlt-Fn}, where @kbd{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 @kbd{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:

@table @kbd
@item ctrl-scrlock
shows the first 0x32 int vectors on debug output
@item alt-scrlock
show the vm86 registers
@item rshift-scrlock
generate an int8 (timer tick)
@item lshift-scrlock
generate an int9 (keyboard service)
@item ctrl-break
ctrl-break as under DOS.
@item ctrl-alt-pgup
reboot DOS. imperfectly done. don't trust this.
@item ctrl-alt-pgdn
exit the emulator (same as using EXITEMU.COM)
@ignore
@item lctrl+rctrl+scrlock
toggle keyboard mouse
@end ignore
@item pause
pause/unpause dosemu.  Extremely useful.
@end table

(most of these are useful for debugging purposes only)

I chose not to use @kbd{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: @code{linux/kernel/chr_drv/keyboard.c}
line: approximately line 103 in kernel version 0.99pl7a

@example
        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;
@end example

This rather crudely redefines the @kbd{SysRq} key, generated by pressing
@kbd{RightAlt-PrintScreen}, to toggle the @code{RAW} keyboard state.  If
you are using dosemu in @code{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 @strong{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.


@node Console Video, VGA, Keyboard, Input/Output
@section Console Video
@cindex Console Video
@comment
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:
@itemize @bullet
@item
very fast
@item
you get color and PC graphics characters
@end itemize

The disadvantages:
@itemize @bullet
@item
still doesn't support screen widths greater than 80 characters
@item
only works on the console (i.e. not over a serial line, not over
a network)
@end itemize


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

@example
        dos -ck > dosdebug </dev/tty7  2>/dev/tty7 &
@end example

@pindex ANSI
@cindex ANSI
@cindex Text modes
@cindex Screen Size
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 @sc{bios}-driven
video emulation along with some @sc{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.  @xref{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.  

@pindex xdosemu
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.


@node VGA, Video Configuration, Console Video, Input/Output
@section VGA
@cindex VGA
@comment

@pindex vgaon.com
@pindex vgaoff.com
@cindex BIOS
@cindex graphics
@pindex tlivesa.com
@pindex fractint
@pindex dosshell
@pindex WordPerfect
@pindex cshow
@pindex Norton Utilities
@cindex Video BIOS


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
@sc{vga} compatibility @footnote{It should be possible to implement
@sc{cga/ega/mda} compatibility also, but there are added difficulties.
Contact me if you are interested.}.

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

These methods initialize the video card's @sc{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 @sc{ansi.sys}.

To return to normal mode, run @code{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:

@itemize @bullet
@item
tlivesa.com, a @sc{vesa} extender for ET4000 cards
@item
dosshell in ALL the video modes, graphics and text.
@item
WordPerfect 5.0 page-preview with the driver set to @sc{ibm 640x480 vga}.

@item Picture viewers:
@table @emph
@item dvpeg
@itemx jpg_menu
@sc{jpeg & gif} viewers.  Both of these detected and used the 15-bit HiColor
capabilities of my ET4000 card.
@item cview
@sc{jpeg & gif} viewer.  requires @code{tlivesa.com}; also utilized the
15- and 16- bit HiColor modes.
@item cshow
the standard CompuServe @sc{gif} viewer
@end table

@item
galactix.  This is your standard arcade game.  Run this with the
@code{-t} command-line option and the speaker ports enabled.
@item
F19, a flight simulator
@item
@pindex SimEarth
@cindex SimEarth
SimEarth @footnote{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.}
@item
SimCity
@item
Flight Simulator (with some keyboard hacks not fully implemented yet)
@item
Windows 3.0 in real mode (with a lot of hacks not fully implemented yet)
@item
fractint (using @code{tlivesa} for the 1024x768x256c mode)
@item
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.
@item
norton utilities in graphics mode; the text mode also ran better with
VGA on.
@item
Scorched Earth, a video game
@end itemize

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

@pindex ANSI.SYS
@cindex ANSI
@cindex Screen drivers

You may choose BIOS-driven graphics through the configuration file
with a directive like @code{video @{ vga console graphics @}}.  
@xref{Video Configuration}.

If a program crashes and leaves you screen in an indeterminate state,
simply exit dosemu, boot a new one, and run @code{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.


@node Video Configuration, , VGA, Input/Output
@section Video Configuration
@cindex Video Configuration
This section describes the run-time configuration options pertaining to
dosemu's display.  @xref{Run-time Configuration}, for an introduction to
the configuration file.

The @code{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:@*
@display
@code{video} @{ [@var{value arg}] @dots{} [@var{predicate}] @dots{} @}
@end display

These are the video words:

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

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

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

@deffn Value Chipset type
Specify the chipset used in the SVGA card.  Currently, only
@var{S3}, @var{Trident} and @var{ET4000} are supported.  The word @var{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.
@end deffn

@deffn 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.
@end deffn

@deffn Predicate Console
Causes dosemu to activate the features only available on the console
@emph{if} dosemu is being run from the console.  These features include
direct screen updates and graphics support.
@end deffn

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

@deffn Predicate Graphics
Allows dosemu to use graphics modes.  At present, this only works with
@var{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.
@end deffn

@deffn 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.
@end deffn

@deffn Predicate VBIOS_copy 
@deffnx Predicate VBIOS_mmap
@deffnx Value VBIOS_file filename
These three predicates specify the method dosemu will use to obtain
access to your @sc{vga bios rom}.  

@var{vbios_mmap} causes dosemu to use the @code{mmap} system call to
directly map the @sc{bios} into the dosemu process's address space.
This has the advantage of making the @sc{rom} write-protected, and is
slightly more memory efficient.

@var{vbios_copy} causes dosemu to copy the entire @sc{rom} from
@file{/dev/mem} into the dosemu's address space.  As this moves all of
the video handling code from slow @sc{rom} into fast @sc{ram}, this
method will probably give better performance.  Think of this as dosemu's
built-in @sc{bios} shadowing.

@var{vbios_file} causes dosemu to read the disk file @var{filename} into
memory.  This is useful for experimenting with alternate @sc{bios}
images.  To create a file calle @file{vbios} with an image of your
@sc{bios rom} in it, execute the following command as root:
@example
/etc/dosemu/getrom > vbios
@end example

@xref{BIOS}, for an explanation of why these directives are necessary.

@var{vbios_mmap} and @var{vbios_copy} both require that the file
@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.
@end deffn

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


@node Peripherals, Memory, Input/Output, top
@chapter Peripherals
@cindex Peripherals

@menu
* Serial Ports::
* Printers::
* Disk Redirector::
* Hard Disks::
* Disk Images::
* Disk Configuration::
@end menu

@node Serial Ports, Printers, , Peripherals
@section Serial Ports
@cindex Serial Ports

The emulator provides some support for both @sc{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 
@footnote{Universal Asynchronous Receiver/Transmitter, the support chip
through which all serial transactions are made} is as faithful as
necessary, there are some features which are not yet emulated:

@itemize @bullet
@item
Overrun, framing, and parity errors.  Overrun should never happen.  The
other errors are difficult to detect from the termios interface.
@item
The modem control lines (DTR, RTS)
@item
Loopback is only partially emulated
@item
the 16550's FIFOs @footnote{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}
@end itemize

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.

@heading Serial Port Configuration
@cindex Serial Port Configuration

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

The @code{serial} word begins a list statement which specifies the
operation of the virtual serial ports.
The general format is this:@*
@display
@code{serial} @{ [@var{value arg}] @dots{} [@var{predicate}] @dots{} @}
@end display

These are the serial words:

@deffn Value Device devname
Causes dosemu to treat the character device special file @var{devname}
as a virtual serial port.  The defaults are @file{/dev/cua0} for the first
serial port and @file{/dev/cua1} for the second serial port.
@end deffn

@deffn Value Base port
Sets the virtual UART's base port address to @var{port}.  The defaults
are 0x3f8 for the first serial port and 0x2f8 for the second serial port.
@end deffn

@deffn Value Interrupt intnum
Sets the virtual UART's interrupt vector number to @var{intnum}.  The
defaults are 0xc for the first serial port and 0xb for the second serial
port. 
@end deffn

@deffn Predicate Modem
@deffnx 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.

@var{Modem} causes dosemu to open the virtual serial port's device at
"bootup" and keep it open until dosemu is shutdown.

@var{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 @var{Mouse} directive does not work in dosemu 0.49.  I hope to
have this fixed fairly soon.
@end deffn



@node Printers, Disk Redirector, Serial Ports, Peripherals
@section Printers
@cindex Printers
@cindex lpd
@pindex lpd
@pindex lpr
@comment

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 @footnote{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.}  Each
virtual printer may be configured separately to act in one of three
ways: 

@enumerate
@item
Save all output to a disk file

@item 
Send all output directly to some device

@item
Send output in groups to some external program, such as the
Linux @code{lpd} daemon.
@end enumerate

@emph{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.  

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

@emph{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.

@heading Printer Configuration
@cindex Printer Configuration

The @code{printer} word begins a list statements which adds
a virtual printer device dosemu's configuration.  This is the general
format of such a statement:
@display
@code{printer @{} [@var{predicate}] @dots{} [@var{value arg}] @dots{} @code{@}}
@end display

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

@deffn Value Command cmd
tells the virtual printer which Linux command to call to print a file.
The default is @code{lpr}.
@end deffn

@deffn 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".
@end deffn

@deffn Value Timeout secs
sets the printer timeout to @var{secs} seconds.  This is the amount of
time the virtual printer device must sit idle @footnote{i.e. receive no
characters} before sending the accumulated output to the print command
as a file.
@end deffn

@deffn Value File name
@deffnx 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 @var{name}, or send characters to the
device named @var{name}.  The timeout parameter is still used to
determine when to flush the printer buffer to the file or device.
@end deffn

A sample section of a configuration file:

@example
; 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 @}
@end example

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

@strong{NOTE:} Make sure that there exsists a directory called
@file{/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:
@display
mkdir /usr/tmp
chmod 1777 /usr/tmp
@end display

@node Disk Redirector, Hard Disks, Printers, Peripherals
@section Disk Redirector
@cindex 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
@dfn{redirection}, thus the program to do that is called a
@dfn{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 @code{LINUX.EXE}
to provide drive redirection.  However, that program had several fatal
faults, which are listed here:

@itemize @bullet
@item
@code{LINUX.EXE} was based on a program called @code{PHANTOM.PAS}, which
was published in Andrew Schulmann's @cite{Undocumented DOS}.  As dosemu
is intended to be a freely available program, inclusion of copyrighted
code is @dots{} discouraged.

@item
@code{LINUX.EXE} suffered from several bugs, the most annoying of which
was the inability to execute @code{.exe} files from a redirected file
system. 

@item
Because of the possibly copyrighted nature of @code{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.
@end itemize

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

@example
device=emufs.sys @var{directory} [@var{flag}]
@end example

@noindent
for every redirected drive you wish to be configured.  @var{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.
@var{flag} is the optional letter @code{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:

@example
mount -t msdos /dev/hda1 /dos1
mount -t msdos /dev/hdb3 /dos2
@end example

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:

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

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

@strong{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:.  @xref{Booting}, for more information on the
types of drives from which dosemu can boot.

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

To generate @code{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 @code{bin86.tar.Z},
available on @emph{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.@refill

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

@itemize @bullet
@item
the original port to dosemu
@item
sane mapping of DOS attributes to Linux attributes
@item
sane handling of uid/gid when run suid root 
@item
integration of the two DOS programs that Mach used---(@code{machfs.sys}
and @code{mfsini.exe})---into one program for Linux (@code{emufs.sys}).
@item
the ability to handle multiple redirected drives
@item
the command line syntax of @code{config.sys} described above,
@item
the read-only flag for redirected drives
@end itemize

@node Hard Disks, Disk Images, Disk Redirector, Peripherals
@section Hard Disks
@cindex Hard Disks
@comment

@pindex Makefile
My current setup in emu.c has two hard disks: hdimage (C:) @footnote{The
drive names in parentheses refer to the dos emulator's view of the
world, not your normal, real-DOS letters.}, 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.  @xref{Configuration}, @xref{Disk
Images}, for further information about floppy configuration.

The @code{hdimage} and @code{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 @code{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.

@noindent
@strong{WARNING WARNING WARNING WARNING WARNING WARNING}@* 
You may @emph{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 @emph{will} let dosemu share access to a Linux-mounted
MS-DOS partition.@*
@strong{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.
@xref{Disk Redirector}, for an explanation.

@menu
* Whole Disk Access::
* Single Partition Access::
@end menu

@node Whole Disk Access, Single Partition Access, Hard Disks, Hard Disks,
@subsection Whole Disk Access
@cindex Whole Disk Access
@cindex Auto-detection, geometry
@cindex Geometry, Hard Disk
@cindex Geometry, Partition

Whole Disk Access allows dosemu to directly read an MS-DOS filesystem
from a @emph{disk} block device (@emph{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
@code{/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.

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


@node  Single Partition Access, , Whole Disk Access, Hard Disks
@subsection Single Partition Access
@cindex 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 @code{/dev/hda}, while SPA access the Partition devices like
@code{/dev/hda1}.  The main difference between these two is that
@code{/dev/hda} can access any part of the disk, while @code{/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 @emph{primary}
partitions only.  You may not enable access to logical partition within
an @emph{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:

@enumerate
@item
@pindex mkpartition
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:

@example
mkpartition /dev/hda 1
@end example

@noindent
sets up the @code{/etc/dosemu/partition} configuration file for SP
access to the first partition of the drive (@code{/dev/hda1}).

@item
Add a line to the @file{/etc/dosemu/config} configuration file like
this:
@example
disk @{ partition /dev/hda1 1 @}
@end example
@end enumerate

@xref{Configuration}, for more information on the files in /etc/dosemu.

@node Disk Images, Disk Configuration, Hard Disks, Peripherals
@section Disk Images
@cindex 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. 

@menu
* Creating hdimage::
* Creating diskimage::
@end menu

@node Creating hdimage, Creating diskimage, , Disk Images
@subsection Creating hdimage
@cindex Creating hdimage
@cindex hdimage
@cindex mkhdimage

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.

@enumerate
@item
First, you must create the actual @code{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 @code{hdimage} of any size.

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

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. 

@example
mkhdimage -h 12 -s 17 -c 300 > hdimage
@end example

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.  @xref{Disk Redirector}).@refill


@pindex fdisk
@item
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:
@example
format c: /s
fdisk /mbr
@end example

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.
@end enumerate
@refill

@node Creating diskimage, , Creating hdimage, Disk Images
@subsection Creating diskimage
@cindex Creating diskimage
@cindex diskimage

There are two ways to create an image of a floppy (@code{diskimage})
file for the Linux DOS emulator. 

@enumerate
@item
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
@code{diskimage}:

@example
dd if=/dev/fd0 of=diskimage bs=16k
@end example

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.  
@xref{Configuration}

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

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

@example
touch diskimage
@end example

This creates a 0-length file called @code{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:

@example
format a: /s
@end example

@end enumerate


@node Disk Configuration, , Disk Images, Peripherals
@section Disk Configuration
@cindex Disk Configuration

The @code{disk} and @code{floppy} words begin list statements which add
a disk or floppy to dosemu's configuration.  This is the general
format of such a statement:@*

@display
@code{disk}    @{ [@var{value arg}] @dots{} [@var{predicate}] @dots{} @}
@code{floppy} @{ [@var{value arg}] @dots{} [@var{predicate}] @dots{} @}
@end display

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

@deffn Value image file
Specifies that the disk is to be configured as an hdimage type file
called @var{file}.
@end deffn

@deffn Value partition partdev partnum
Specifies that the disk is to be configured as a directly accessed
partition, which Linux accesses as device special file @var{partdev};
the cardinal partition number @var{partnum}, which must be between 1 and
4, is the partition's number in the partition table.@*
@xref{Single Partition Access}
@end deffn

@deffn Value wholedisk diskdev
Specifies that the disk is to be configured as a diretly accessed
disk, which Linux refers to as device special file @var{diskdev}.  @*
@xref{Whole Disk Access}.
@end deffn


Some words are only useful for floppy disk configuration:

@cindex CMOS
@cindex Floppy drive
@deffn Predicate threeinch
@deffnx Predicate fiveinch
Specifies whether the floppy drive should show up in the @sc{cmos}
configuration as a five inch (1.2 MB) drive, or a three inch (1.44 MB)
drive. 
@end deffn

@deffn Value Device dev
Specifies the device @var{dev} as the floppy disk.  @var{dev} may be
either a block special device which points to a real floppy disk, or a
floppy disk image.  @xref{Creating diskimage}.
@end deffn

These words apply to both floppy and hard disks:

@deffn Value Sectors count
Configures the specified disk to have @var{count} sectors.
@end deffn

@deffn Value Heads count
Configures the specified disk to have @var{count} heads.
@end deffn

@deffn Value Cylinders count
Configures the specified disk to have @var{count} cylinders.
@end deffn

@deffn Predicate readonly
Sets the relevant disk to read-only mode.  This still behaves strangely.
@xref{Bugs}, for more information.
@end deffn

@strong{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.



@node Memory, Miscellaneous , Peripherals, top
@chapter Memory
@cindex Memory

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

@menu
* DOS memory::
* XMS::
* EMS::
* Memory Configuration::
@end menu

@node DOS memory, XMS, , Memory
@section DOS memory
@cindex DOS memory
@cindex Normal 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 @sc{vga} video, so specifying @sc{vga}
through either of the option methods will set the base memory size to
640K.  If you need additional DOS memory, look into @sc{xms} and
@sc{ems}.  @xref{XMS}, @pxref{EMS}, for more information on increasing
the amount of free memory.


@node XMS, EMS, DOS memory, Memory
@section XMS
@cindex XMS
@cindex Extended Memory Specification
@cindex HMA

Adam Goldberg (@code{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:

@itemize @bullet
@item
Extended Memory Block (EMB) Functions
@item
Upper Memory Block (UMB) Functions
@item
High Memory Area (HMA) Functions
@item
32-bit Extended Memory Block Functions (new with XMS 3.0)
@end itemize

You can specify the maximum amount of memory the emulator can use in two
ways: through the @code{-x} @var{size} command line option, and through the
run-time configuration file (@pxref{Memory Configuration}).
@var{size} is given in kilobytes.

If you enable XMS, you can put the line

@example
 dos=high,umb
@end example

@noindent
in your @code{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 @sc{XMS} driver, such as HIMEM.SYS.  
dosemu uses its own internal driver to provide @sc{XMS} services.

@node EMS, Memory Configuration, XMS, Memory
@section EMS
@cindex EMS
@cindex Expanded Memory Specification

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!]  @xref{Mach}, 
for more info about Mach.

You can specify the maximum amount of memory the emulator can use in two
ways: through the @code{-x} @var{size} command line option, and through the
run-time configuration file (@pxref{Memory Configuration}).
@var{size} is given in kilobytes.

EMS requires a kernel patch, included with dosemu.  It adds an
@code{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 @sc{EMS} driver, such as EMM386.EXE.
dosemu uses its own internal driver to provide @sc{EMS} services.

@node Memory Configuration, , EMS, Memory
@section Memory Configuration
@cindex Memory Configuration

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

@deffn Value DOSmem size
Sets the base DOS memory size to @var{size} kilobytes.  Default size is
640k.   The maximum is 734K.
@end deffn

@deffn Value EMS size
Activates Expanded Memory Specification 4.0 emulation with a memory pool
size of @var{size} kilobytes.
@end deffn

@deffn Value XMS size
Activates Extended Memory Specification 3.0 emulation with a memory pool
size of @var{size} kilobytes.
@end deffn

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

@node Miscellaneous, Programs That Work, Memory, top
@chapter Miscellaneous
@cindex Miscellaneous

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

@menu
* BIOS::
* CPU type::
* TTY copy::
@end menu

@node BIOS, CPU type, Miscellaneous, Miscellaneous
@section BIOS
@cindex BIOS
@comment
The "-b" option maps the video @sc{bios rom} at c000:0000 
into the emulator's address space. @footnote{This option is automatically
activated by using @sc{bios}-driven video.}

Do not use this option unless necessary, as the XMS Upper Memory Block
support uses the address space normally occupied by the @sc{rom}s for
Upper Memory Blocks; mapping in the @sc{bios} reduces the amount of
memory available for @sc{xms}.  @xref{XMS}, for more information about
Upper Memory Blocks.

@strong{NOTE:} You may suffer @sc{rom} corruption problems if your
computer uses shadow ram to speed @sc{bios} access times.  If this
happens, turn off @sc{rom} shadowing in your system's @sc{cmos} setup
@footnote{Linux can run into other problems if you have shadow @sc{rom}
enabled, so it's always a good idea to turn it off}.

Alternately, you may use the @var{vbios_copy} and @var{vbios_file} video
directives.  @xref{Video Configuration}, for more information on ways to
prevent @sc{bios} corruption.


@node CPU type, TTY copy , BIOS, Miscellaneous
@section CPU type
@cindex 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 @cite{Intel 486 Programmer's Handbook}.
Suffice it to say that the test relies upon various instruction
peculiarities and the behavior of bits in the @code{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:

@table @code
@item -2
act as an 80286
@item -3
act as an 80386 (default)
@item -4
act as an 80486
@end table

The run-time configuration file may also be used to select the processor
to be emulated.  @xref{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.

@node TTY copy, , CPU type, Miscellaneous
@section TTY copy
@cindex TTY copy
@cindex Interactive debugging
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 :-).



@node Programs That Work, Bugs, Miscellaneous, top
@chapter Programs That Work
@cindex 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.
@xref{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:

@itemize @bullet
@item
Turbo Pascal 5.5
@item
PC Tools PCShell (and compress)
@item
QEdit
@item
Borland TASM/TLINK
@item
doskey (might not be impressive, but it's useful)
@item
4DOS 4.0
@item
HelpPC 2.1
@item
a86 and d86 (a shareware assembler and debugger)
@item
WordPerfect 5.0
@item
Microsoft Word 5.5
@item
Norton Utilities v6.0 @footnote{Go into configuration and turn off
"Zooming Boxes" under the Video menu.  This really speeds things up.}
@item
Checkit
@item
Turbo Debugger 3.0
@item
A very old version of Turbo C
@item
pkzip 2.04e
@item
MKS utilities
@item
Elvis 1.5
@item
SimEarth
@item
ColorView/386
@item
Telix & Kermit (at low baud rates)
@item
MouseSystems mouse and MicroSoft mouse driver (mscmouse.com)
@item
dBase III+
@end itemize

Here are some programs that are @emph{reported} to work:

@itemize @bullet
@item
DR-DOS 6.0
@item
SuperStor
@item
Stacker
@item
uEmacs (don't even think about demacs!)
@item
Minitab
@item
the Big Mouth Voicemail card @footnote{Ed Carp, erc@@apple.com posted
some patches to get it to work}
@item
Managing Your Money,
@item
Quicken 4.0
@item
FoxPro 2.0
@item
Microsoft Word 5.0
@item
Turbo C++ 1.0
@item
Alpha-4 2.1 (database)
@item
Microsoft Multiplan 4.2
@item
Lotus 123 v2.2
@end itemize


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


@node Bugs, Changes, Programs That Work, top
@chapter Bugs
@cindex Bugs
@comment node, next, previous, up

I probably already know about the @strong{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, @emph{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.

@cindex e-mail
@cindex address
@cindex Contacting the Author
If you need to reach me, I can receive e-mail at this Internet address:

@example
gt8134b@@prism.gatech.edu
@end example

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.

@cindex mailing list
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
@code{linux-activists-request@@niksula.hut.fi} with a message body of
@code{HELP}.@refill

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 @var{Mouse} and @var{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 @code{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 @code{-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:

@example
/* selected "Turbo Mode" here, screen turned blue */
@end example

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


@node Changes, Concept Index, Bugs, top
@chapter Changes
@cindex 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. @xref{Updating from 0.48pl1}, for more information on
upgrading your current dosemu installation.

@itemize @bullet
@item
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.
@xref{Memory}.

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

@item
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 :-)

@item
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.  

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

@item
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.

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

@item
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.

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

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

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

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

@item
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...
@xref{Configuration}.

@item
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.
@xref{Disk Redirector}

@item
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.
@xref{Disk Images}.  @xref{Updating from 0.48pl1}.

@item
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 :-)
@xref{Hard Disks}.

@item
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.
@xref{Memory}.

@item
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; @xref{Configuration}, for
more information about kernel versions and dosemu).

@item
more properly handles a monochrome video card with MDA_VIDEO

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

@item
new printer handler can now send jobs to @code{lpr} (or whatever other
command you like).

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

@item
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...

@item
added the run-time configuration file parser

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

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

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

@item
a lot of little things here and there.
@end itemize

@setchapternewpage odd
@node Concept Index, Program/File Index, Changes, Top
@unnumbered Concept Index

@printindex cp

@node Program/File Index, , Concept Index, Top
@unnumbered Program/File Index

@printindex pg

@contents
@bye
