  DOSEmu
  The DOSEmu team Edited by Alistair MacDonald  <alis-
  tair@slitesys.demon.co.uk>
  For DOSEMU v0.98 pl0.0

  This document is the amalgamation of a series of README files which
  were created to deal with the lack of DOSEmu documentation.
  ______________________________________________________________________

  Table of Contents:

  1.      Introduction

  2.      Runtime Configuration Options

  2.1.    Format of /etc/dosemu.conf

  2.1.1.  Controling amount of debug output

  2.1.2.  Basic emulaton settings

  2.1.3.  Code page and character set

  2.1.4.  Terminals

  2.1.5.  Keyboard settings

  2.1.6.  X Support settings

  2.1.7.  Video settings ( console only )

  2.1.8.  Disks and floppies

  2.1.9.  COM ports and mices

  2.1.10. Printers

  2.1.11. Networking under DOSEMU

  2.1.12. Sound

  3.      Security

  4.      Directly executable DOS applications using dosemu (DEXE)

  4.1.    Making and Using DEXEs

  4.2.    Using binfmt_misc to spawn DEXEs directly

  4.3.    Making a bootable hdimage for general purpose

  4.4.    Accessing hdimage files using mtools

  5.      Sound

  5.1.    Using the MPU-401 "Emulation".

  5.2.    The MIDI daemon

  5.3.    Disabling the Emulation at Runtime

  6.      Using Lredir

  6.1.    how do you use it?

  6.2.    Other alternatives using Lredir

  7.      Running dosemu as a normal user

  8.      Using CDROMS

  8.1.    The built in driver

  9.      Logging from DOSEmu

  10.     Using X

  10.1.   Latest Info

  10.2.   Slightly older information

  10.3.   Status of X support (Sept 5, 1994)

  10.3.1. Done

  10.3.2. ToDo (in no special order)

  10.4.   The appearance of Graphics modes (November 13, 1995)

  10.4.1. vgaemu

  10.4.2. vesa

  10.4.3. X

  10.5.   The new VGAEmu/X code (July 11, 1997)

  11.     Running Windows under DOSEmu

  11.1.   Windows 3.0 Real Mode

  11.2.   Windows 3.1 Protected Mode

  11.3.   Windows 3.x in xdos

  12.     Mouse Garrot

  13.     Running a DOS-application directly from Unix shell

  13.1.   Using the keystroke and commandline options.

  13.2.   Using an input file

  14.     Setting HogThreshold

  15.     Commands & Utilities

  15.1.   Programs

  15.2.   Drivers

  16.     Keymaps

  17.     Networking using DOSEmu

  17.1.   The DOSNET virtual device.

  17.2.   Setup for virtual TCP/IP

  17.3.   Full Details

  17.3.1. Introduction

  17.3.2. Design

  17.3.3. Implementation

  17.3.4. Virtual device 'dsn0'

  17.3.5. Packet driver code

  17.3.6. Conclusion

  17.3.6.1.       Telnetting to other Systems

  17.3.6.2.       Accessing Novell netware

  18.     Using Windows and Winsock

  18.1.   LIST OF REQUIRED SOFTWARE

  18.2.   STEP BY STEP OPERATION (LINUX SIDE)

  18.3.   STEP BY STEP OPERATION (DOS SIDE)
  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn

  This documentation is derived from a number of smaller documents. This
  makes it easier for individuals to maintain the documentation relevant
  to their area of expertise. Previous attempts at documenting DOSEmu
  failed because the documentation on a large project like this quickly
  becomes too much for one person to handle.

  22..  RRuunnttiimmee CCoonnffiigguurraattiioonn OOppttiioonnss

  This section of the document by Hans, <lermen@fgan.de>. Last updated
  on Mar 20, 1998.

  Most of DOSEMU configuration is done during runtime and per default it
  expects the system wide configuration file /etc/dosemu.conf optionally
  followed by the users  /.dosemurc and additional configurations
  statements on the commandline (-I option). The builtin configuration
  file of a DEXE file is passed using the -I technique, hence the rules
  of -I apply.

  In fact /etc/dosemu.conf and  /.dosemurc (which have identical syntax)
  are included by the systemwide configuration script
  /var/lib/dosemu/global.conf, but as a normal user you won't ever think
  on editing this, only dosemu.conf and your personal  /.dosemurc.  The
  syntax of global.conf is described in detail in README-tech.txt, so
  this is skipped here. However, the option -I string too uses the same
  syntax as global.conf, hence, if you are doing some special stuff
  (after you got familar with DOSEMU) you may need to have a look there.

  In DOSEMU prior to 0.97.5 the private configuration file was called
   /.dosrc (not to be confused with the new  /.dosemurc). This will work
  as expected formerly, but is subject to be nolonger supported in the
  near future.  This (old)  /.dosrc is processed _a_f_t_e_r global.conf and
  follows (same as -I) the syntax of global.conf (see README-tech.txt).

  The first file expected (and interpreted) before any other
  configuration (such as global.conf, dosemu.conf and  /.dosemurc) is
  /etc/dosemu.users.  Within /etc/dosemu.users the general permissions
  are set:

  +o  which users are allowed to use DOSEMU.

  +o  which users are allowed to use DOSEMU suid root.

  +o  which users are allowed to have a private lib dir.

  +o  what kind of access class the user belongs to.

  +o  what special configuration stuff the users needs

  and further more:

  +o  wether the lib dir (/var/lib/dosemu) resides elsewhere.

  +o  setting the loglevel.

  Except for lines starting with `xxx=' (explanation below), each line
  in dosemu.user corresponds to exactly _o_n_e valid user count, the
  special user `all' means any user not mentioned earlier. Format:

         [ <login> | all ] [ confvar [ confvar [ ... ] ] ]

  The below example is from etc/dosemu.users.secure, which you may copy
  to /etc/dosemu.users.

         root c_all     # root is allowed to do all weird things
         nobody nosuidroot guest # variable 'guest' is checked in global.conf
                                 # to allow only DEXE execution
         guest nosuidroot guest  # login guest treated as `nobody'
         myfriend c_all unrestricted private_setup
         myboss nosuidroot restricted private_setup
         all nosuidroot restricted # all other users have normal user restrictions

  Note that the above `restricted' is checked in global.conf and will
  disable all secure relevant feature. Setting `guest' will force set-
  ting `restricted' too.

  The use of `nosuidroot' will force a suid root dosemu binary to exit,
  the user may however use a non-suid root copy of the binary.  For more
  information on this look at README-tech, chapter 11.1 `Privileges and
  Running as User'

  Giving the keyword `private_setup' to a user means he/she can have a
  private DOSEMU lib under $HOME/.dosemu/lib. If this directory is
  existing, DOSEMU will expect all normally under /var/lib/dosemu within
  that directory, including `global.conf'. As this would be a security
  risc, it only will be allowed, if the used DOSEMU binary is non-suid-
  root. If you realy trust a user you may additionally give the keyword
  `unrestricted', which will allow this user to execute a suid-root
  binary even on a private lib directory (though, be aware).

  In addition, dosemu.users can be used to define some global settings,
  which must be known before any other file is accessed, such as:
         default_lib_dir= /opt/dosemu  # replaces /var/lib/dosemu
         log_level= 2                  # highest log level

  With `default_lib_dir=' you may move /var/lib/dosemu elsewere, this
  mostly is interesting for distributors, who want it elswere but won't
  patch the DOSEMU source just for this purpose. But note, the dosemu
  supplied scripts and helpers may need some adaption too in order to
  fit your new directory.

  The `log_level=' can be 0 (never log) or 1 (log only errors) or 2 (log
  all) and controls the ammount written to the systems log facility
  (notice).  This keyword replaces the former /etc/dosemu.loglevel file,
  which now is obsolete.

  Nevertheless, for a first try of DOSEMU you may prefer
  etc/dosemu.users.easy, which just contains

         root c_all
         all c_all

  to allow evrybody all weird things. For more details on security
  issues have a look at README-tech.txt chapter 2.

  After /etc/dosemu.users /etc/dosemu.conf (via global.conf) is
  interpreted, and only during global.conf parsing access to all
  configuration options is allowed. Your personal  /.dosemurc is
  included directly after dosemu.conf, but has less access rights (in
  fact the lowest level), all variables you define within  /.dosemurc
  transparently are prefixed with `dosemu_' such that the normal
  namespace cannot be polluted (and a hacker cannot overwrite security
  relevant enviroment variables). Within global.conf only those
   /.dosemurc created variables, that are needed are taken over and may
  overwrite those defined in /etc/dosemu.conf.

  The dosemu.conf (global.conf) may check for the configuration
  variables, that are set in /etc/dosemu.users and optionaly include
  further configuration files. But once /etc/dosemu.conf (global.conf)
  has finished interpretation, the access to secure relevant
  configurations is (class-wise) restricted while the following
  interpretation of (old) .dosrc and -I statements.

  For more details on security setings/issues look at README-tech.txt,
  for now (using DOSEMU the first time) you should need only the below
  description of /etc/dosemu.conf ( /.dosemurc)

  22..11..  FFoorrmmaatt ooff //eettcc//ddoosseemmuu..ccoonnff

  All settings in dosemu.conf are just variables, that are interpreted
  in /var/lib/dosemu/global.conf and have the form of

    $_xxx = (n)
  or
    $_zzz = "s"

  where `n' ist a numerical or boolean value and `s' is a string.  Note
  that the brackets are important, else the parser won't decide for a
  number expression. For numers you may have complete expressions ( such
  as (2*1024) ) and strings may be concatenated such as

         $_zzz = "This is a string containing '", '"', "' (quotes)"

  Hence a comma separated list of strings is concatenated.

  22..11..11..  CCoonnttrroolliinngg aammoouunntt ooff ddeebbuugg oouuttppuutt

  DOSEMU will help you finding problems, when you enable its debug
  messages.  These will go into the file, that you defined via the `-o
  file' or `-O' commandline option (the later prints to stderr). In
  dosemu.conf you can preset this via

         $_debug = "-a"

  where the string contains all you normally may pass to the `-D' com-
  mandline option (look at the man page for details).

  22..11..22..  BBaassiicc eemmuullaattoonn sseettttiinnggss

  To enable INT08 type timer interrupts set the below on or off

         $_timint = (on)

  Wether a numeric processor should be shown to the DOS space

         $_mathco = (on)

  Which type of CPU should be emulated (NOTE: this is not the one you
  are running on, but your setting may not exeed the capabilities of the
  running CPU). Valid values are:  8034586

    $_cpu = (80386)

  To let DOSEMU use the Pentium cycle counter (if availabe) to do better
  timing use the below

         $_rdtsc = (on)   # or off

  For the above `rdtsc' feature DOSEMU needs to know the exact CPU
  clock, it normally calibrates it itself, but is you encounter a wrong
  mesurement you may overide it such as

         $_cpuspeed = (166.666)  # 0 = let DOSEMU calibrate

  NOTE: `$_rdtsc' and `$_cpuspeed' can _n_o_t be overwritten by
   /.dosemurc.

  If you have a PCI board you may allow DOSEMU to access the PCI
  configuration space by defining the below

         $_pci = (on)    # or off

  Defining the memory layout, which DOS should see:

         $_xms = (1024)          # in Kbyte
         $_ems = (1024)          # in Kbyte
         $_ems_frame = (0xe000)
         $_dpmi = (off)          # in Kbyte
         $_dosmem = (640)        # in Kbyte, < 640

  Note that (other as in native DOS) each piece of mem is separate,
  hence DOS perhaps will show other values for 'extended' memory. To
  enable DPMI (by giving it memory) is a security concern, so you should
  either _n_o_t give access to dosemu for normal users (via
  /etc/dosemu.users) or give those users the `restricted' attribute (see
  above).

  There are some features in DOSEMU, that may violate system security
  and which you should not use on machines, which are `net open'. To
  have atleast a minimum of protection against intruders, use the
  folling:

         $_secure ="ngd"  # secure for: n (normal users), g (guest), d (dexe)
                          # empty string: depending on 'restricted'

  The above is a string of which may be given or not, hence

         $_secure ="d"

  would only effect execution of DEXEs. If you are not a `restricted'
  user (as given via /etc/dosemu.users) the above settings won't apply.
  To disable security checking atall set

         $_secure ="0"

  NOTE: `$_secure' can _n_o_t be overwritten by  /.dosemurc.

  For the similar reasons you may `backout' some host, which you don't
  like to have access to dosemu

         $_odd_hosts = ""    # black list such as
                             #      "lucifer.hell.com billy.the.cat"
         $_diskless_hosts="" # black list such as "hacker1 newbee gateway1"

  The items in the lists are blank separated, `odd_hosts' checks for
  remote logins, `diskless_hosts' are meant to be maschines, that mount
  a complete tree, hence the checked host is the host DOSEMU is running
  on (not the remote host). However, read README-tech,txt for more
  details on what actually is disabled.

  NOTE: `$_*_hosts' can _n_o_t be overwritten by  /.dosemurc.

  If you want mixed operation on the filesystem, from which you boot
  DOSEMU (native and via DOSEMU), it may be necessary to have two
  separate sets of `config.sys,autoexec.bat,system.ini'. DOSEMU can fake
  a different file extension, so DOS will get other files when running
  under DOSEMU.

         $_emusys = ""    # empty or 3 char., config.sys   -> config.XXX
         $_emubat = ""    # empty or 3 char., autoexec.bat -> autoexec.XXX
         $_emuini = ""    # empty or 3 char., system.ini   -> system.XXX

  As you would realize at the first glance: DOS will _n_o_t have the the
  CPU for its own. But how much it gets from Linux, depends on the
  setting of `hogthreshold'.  The HogThreshold value determines how nice
  Dosemu will be about giving other Linux processes a chance to run.

         $_hogthreshold = (1)   # 0 == all CPU power to DOSEMU
                                # 1 == max power for Linux
                                # >1   the higher, the slower DOSEMU will be

  If you have hardware, that is not supported under Linux but you have a
  DOS driver for, it may be necessary to enable IRQ passing to DOS.

         $_irqpassing = ""  # list of IRQ number (2-15) to pass to DOS such as
                            # "3 8 10"

  Here you tell DOSEMU what to do when DOS wants let play the speaker:

         $_speaker = ""     # or "native" or "emulated"

  And with the below may gain control over _r_e_a_l ports on you machine.
  But: WWAARRNNIINNGG:: GGIIVVIINNGG AACCCCEESSSS TTOO PPOORRTTSS IISS BBOOTTHH AA SSEECCUURRIITTYY CCOONNCCEERRNN AANNDD
  SSOOMMEE PPOORRTTSS AARREE DDAANNGGEERROOUUSS TTOO UUSSEE..  PPLLEEAASSEE SSKKIIPP TTHHIISS SSEECCTTIIOONN,, AANNDD DDOONN''TT
  FFIIDDDDLLEE WWIITTHH TTHHIISS SSEECCTTIIOONN UUNNLLEESSSS YYOOUU KKNNOOWW WWHHAATT YYOOUU''RREE DDOOIINNGG..

         $_ports = ""  # list of portnumbers such as "0x1ce 0x1cf 0x238"
                       # or "0x1ce range 0x280,0x29f 310"
                       # or "range 0x1a0,(0x1a0+15)"

  NOTE: `$_ports' can _n_o_t be overwritten by  /.dosemurc.

  22..11..33..  CCooddee ppaaggee aanndd cchhaarraacctteerr sseett

  To select the character set and code page for use with DOSEMU you have

         $_term_char_set = "XXX"

  where XXX is one of

     iibbmm
        the text is taken whithout translation, it is to the user to
        load a proper DOS font (cp437.f16, cp850.f16 or cp852.f16 on the
        console).

     llaattiinn
        the text is processed using cp437->iso-8859-1 translation, so
        the font used must be iso-8859-1 (eg iso01.f16 on console);
        which is the default for unix in western languages countries.

     llaattiinn11
        like latin, but using cp850->iso-8859-1 translation (the
        difference between cp437 and cp850 is that cp437 uses some chars
        for drawing boxes while cp850 uses them for accentuated letters)

     llaattiinn22
        like latin1 but uses cp852->iso-8859-2 translation, so
        translates the default DOS charset of eastern european countries
        to the default unix charset for those countries.

  The default one is ``latin'' and if the string is empty, then an auto-
  matic attempt is made: ``ibm'' for remote console and ``latin'' for
  anything else.  Depending on the charset setting the (below described)
  keyboard layouts and/or the terminal behave may vary. You need to know
  the correct code page your DOS is configured for in order to get the
  correct results.  For most western european countries 'latin' should
  be the correct setting.

  22..11..44..  TTeerrmmiinnaallss

  This section applies whenever you run DOSEMU remotely or in an xterm.
  Color terminal support is now built into DOSEMU.  Skip this section
  for now to use terminal defaults, until you get DOSEMU to work.

         $_term_color = (on)   # terminal with color support
         $_term_updfreq = (4)  # time between refreshs (units: 20 == 1 second)
         $_escchar = (30)      # 30 == Ctrl-^, special-sequence prefix

  `term_updfreq' is a number indicating the frequency of terminal
  updates of the screen. The smaller the number, the more frequent.  A
  value of 20 gives a frequency of about one per second, which is very
  slow.  `escchar' is a number (ascii code below 32) that specifies the
  control character used as a prefix character for sending alt, shift,
  ctrl, and function keycodes.  The default value is 30 which is Ctrl-^.
  So, for example,

         F1 is 'Ctrl-^1', Alt-F7 is 'Ctrl-^s Ctrl-^7'.
         For online help, press 'Ctrl-^h' or 'Ctrl-^?'.

  22..11..55..  KKeeyybbooaarrdd sseettttiinnggss

  When running DOSEMU from console (also remote from console) or X you
  may need to define a proper keyboard layout. This is done either by
  choosing one on the internal keytables or by loading an external
  keytable from /var/lib/dosemu/keymap/* (which you may modify according
  to your needs). Both sets have identical names (though you may add any
  new one to /var/lib/dosemu/keymap/*):

         be              es-latin1       hu-latin2       sg
         de              finnish         it              sg-latin1
         de-latin1       finnish-latin1  keyb-no         sw
         dk              fr              no-latin1       uk
         dk-latin1       fr-latin1       po              us
         dvorak          hu              sf
         es              hu-cwi          sf-latin1       jp106

  You define an internal keytable such as

         $_layout = "name"

  where `name' is one of the above. To load a keytable you just prefix
  the string with "load" such as

         $_layout = "load de-latin1"

  Note, however, that you have to set

         $_X_keycode = (on)

  to use this feature under X, because per default the keytable is
  forced to be neutral (us). Normally you will have the correct settings
  of your keyboard given by the X-server.

  When being on console you might wish to use raw keyboard, especially
  together with some games, that don't use the BIOS/DOS to get their
  keystrokes.

         $_rawkeyboard = (1)

  However, be carefull, when the application locks, you may not be able
  to switch your console and recover from this. For details on recover-
  ing look at README-tech.txt (Recovering the console after a crash).

  NOTE: `$_rawkeyboard' can _n_o_t be overwritten by  /.dosemurc.

  The `keybint (on)' allows more accurate of keyboard interrupts, It is
  a bit unstable, but makes keyboard work better when set to "on".

         $_keybint = (on)     # emulate PCish keyboard interrupt

  22..11..66..  XX SSuuppppoorrtt sseettttiinnggss

  If DOSEMU is running in its own X-window (not xterm), you may need to
  tailor it to your needs. Here a summary of the settings and a brief
  description what they mean. A more detailed description of values one
  can be found at chapter 2.2.14 (X Support settings) of README-tech.txt

       $_X_updfreq = (5)       # time between refreshs (units: 20 == 1 second)
       $_X_title = "DOS in a BOX" # Title in the top bar of the window
       $_X_icon_name = "xdos"  # Text for icon, when minimized
       $_X_keycode = (off)     # on == translate keybord via dosemu keytables
       $_X_blinkrate = (8)     # blink rate for the cursor
       $_X_font = ""           # basename from /usr/X11R6/lib/X11/fonts/misc/*
                               # (without extension) e.g. "vga"
       $_X_mitshm = (on)       # Use shared memory extensions
       $_X_sharecmap = (off)   # share the colormap with other applications
       $_X_fixed_aspect = (on) # Set fixed aspect for resize the graphics window
       $_X_aspect_43 = (on)    # Always use an aspect ratio of 4:3 for graphics
       $_X_lin_filt = (off)    # Use linear filtering for >15 bpp interpol.
       $_X_bilin_filt = (off)  # Use bi-linear filtering for >15 bpp interpol.
       $_X_mode13fact = (2)    # initial factor for video mode 0x13 (320x200)
       $_X_winsize = ""        # "x,y" of initial windows size
       $_X_gamma = (1.0)       # gamma correction
       $_X_vgaemu_memsize = (1024) # size (in Kbytes) of the frame buffer
                               # for emulated vga
       $_X_lfb = (on)  # use linear frame buffer in VESA modes
       $_X_pm_interface = (on) # use protected mode interface for VESA modes
       $_X_mgrab_key = ""      # KeySym name to activate mouse grab, empty == off
       $_X_vesamode = ""       # "xres,yres ... xres,yres"
                               # List of vesamodes to add. The list has to contain
                               # SPACE separated "xres,yres" pairs

  22..11..77..  VViiddeeoo sseettttiinnggss (( ccoonnssoollee oonnllyy ))

  _!_!_W_A_R_N_I_N_G_!_!_: _I_F _Y_O_U _E_N_A_B_L_E _G_R_A_P_H_I_C_S _O_N _A_N _I_N_C_O_M_P_A_T_I_B_L_E _A_D_A_P_T_O_R_, _Y_O_U
  _C_O_U_L_D _G_E_T _A _B_L_A_N_K _S_C_R_E_E_N _O_R _M_E_S_S_Y _S_C_R_E_E_N _E_V_E_N _A_F_T_E_R _E_X_I_T_I_N_G _D_O_S_E_M_U_.
  _R_e_a_d _d_o_c_/_R_E_A_D_M_E_-_t_e_c_h_._t_x_t _(_R_e_c_o_v_e_r_i_n_g _t_h_e _c_o_n_s_o_l_e _a_f_t_e_r _a _c_r_a_s_h_)_.

  Start with only text video using the following setup in dosemu.conf

         $_video = "vga"         # one of: plainvga, vga, ega, mda, mga, cga
         $_console = (0)         # use 'console' video
         $_graphics = (0)        # use the cards BIOS to set graphics
         $_videoportaccess = (1) # allow videoportaccess when 'graphics' enabled
         $_vbios_seg = (0xc000)  # set the address of your VBIOS (e.g. 0xe000)
         $_vbios_size = (0x10000)# set the size of your BIOS (e.g. 0x8000)
         $_vmemsize = (1024)     # size of regen buffer
         $_chipset = ""
         $_dualmon = (0)         # if you have one vga _plus_ one hgc (2 monitors)

  After you get it `somehow' working and you have one of the DOSEMU
  supported graphic cards you may switch to graphics mode changing the
  below

         $_graphics = (1)        # use the cards BIOS to set graphics

  If you have a 100% compatible standard VGA card that _m_a_y work,
  however, you get better results, if your card has one of the DOSEMU
  supported video chips and you tell DOSEMU to use it such as

         $_chipset = "s3"        # one of: plainvga, trident, et4000, diamond,
                                 # avance, cirrus, matrox, wdvga, paradise

  Note, `s3' is only an example, you _m_u_s_t set the correct video chip
  else it most like will crash your screen.

  NOTE: `video setting' can _n_o_t be overwritten by  /.dosemurc.

  22..11..88..  DDiisskkss aanndd ffllooppppiieess

  The parameter settings via dosemu.conf are tailored to fit the
  recomended usage of disk and floppy access. There are other methods
  too, but for these you have to look at README-tech.txt (and you may
  need to modify global.conf).  We strongly recommend that you use the
  proposed techique. Here the normal setup:

         $_vbootfloppy = ""    # if you want to boot from a virtual floppy:
                               # file name of the floppy image under /var/lib/dosemu
                               # e.g. "floppyimage" disables $_hdimage
                               #      "floppyimage +hd" does _not_ disable $_hdimage
         $_floppy_a ="threeinch" # or "fiveinch" or empty, if not existing
         $_floppy_b = ""       # dito for B:

         $_hdimage = "hdimage.first" # list of hdimages under /var/lib/dosemu
                               # assigned in this order such as
                               # "hdimage_c hdimage_d hdimage_e"
         $_hdimage_r = $_hdimage # hdimages for 'restricted access (if different)

  When you installed DOSEMU (`make install') you will have a bootable
  hdimage in the file /var/lib/dosemu/hdimage.first. It contains a very
  tiny installation of FreeDos, just to show you that it works. A
  hdimage is a file containing a virtual image of a DOS-FAT filesystem.
  Once you have booted it, you (or autoexec.bat) can use `lredir' to
  access any directory in your Linux tree as DOS drive (a -t msdos
  mounted too). Look at chapter 6 (Using Lredir) and for more details on
  creating your own (better) hdimage look at chapter 4.3 of this README
  (Making a bootable hdimage for general purpose). Chapter 4.4 also
  describes how to import/export files from/to a hdimage.

  Now, what does the above `vbootfloppy' mean? Alternatively of booting
  from a virtual `disk' you may have an image of a virtual `floppy'
  which you just created such as `dd if=/dev/fd0 of=floppy_image'. If
  this floppy contains a bootable DOS, then

         $_vbootfloppy = "floppy_image"

  will boot that floppy. Once running in DOS you can make the floppy
  available by (virtually) removing the `media' via `bootoff.com'.  If
  want the disk access specified via `$_hdimage' anyway, you may add the
  keyword `+hd' such as

         $_vbootfloppy = "floppy_image +hd"

  In some rare cases you may have problems accessing Lredir'ed drives
  (especially when your DOS application refuses to run on a 'network
  drive'), though I personally never happened to fall into one of this.
  For this to overcome you may need to use socalled `partition access'.
  The odd with this kind of access is, that you _n_e_v_e_r should have those
  partition mounted in the Linux file system at the same time as you use
  it in DOSEMU (which is quite uncomfortable and dangerous on a
  multitasking OS such as Linux ). Though global.conf checks for mounted
  partitions, there may be races that are not caught. In addition, when
  your DOSEMU crashes, it may leave some FAT sectors unflushed to the
  disk, hence destroying the partition.  Anyway, if you think you need
  it, here is how you `assign' real DOS partitions to DOSEMU:

         $_hdimage = "hdimage.first /dev/hda1 /dev/sdc4:ro"

  The above will have `hdimage.first' as booted drive C:, /dev/hda1 as
  D: (read/write) and /dev/sdc4 as E: (readonly). You may have any kind
  of order within `$_hdimage', hence

         $_hdimage = "/dev/hda1 hdimage.first /dev/sdc4:ro"

  would have /dev/hda1 as booted drive C:. Note that the access to the
  /dev/* devices _m_u_s_t be exclusive (no other process should use it)
  except for `:ro'.

  22..11..99..  CCOOMM ppoorrttss aanndd mmiicceess

  We have simplified the configuration for mices and serial ports and
  check for depencies between them. If all strings in the below example
  are empty, then no mouse and/or COM port is available. Note. that you
  need _n_o mouse.com driver installed in your DOS environment, DOSEMU has
  the mousedriver builtin. The below example is such a setup

    $_com1 = ""           # e.g. "/dev/mouse" or "/dev/cua0"
    $_com2 = "/dev/modem" # e.g. "/dev/modem" or "/dev/cua1"

    $_mouse = "microsoft" # one of: microsoft, mousesystems, logitech,
                          # mmseries, mouseman, hitachi, busmouse, ps2
    $_mouse_dev = "/dev/mouse" # one of: com1, com2 or /dev/mouse
    $_mouse_flags = ""    # list of none or one or more of:
                          # "emulate3buttons cleardtr"
    $_mouse_baud = (0)    # baudrate, 0 == don't set

  The above example lets you have your modem on COM2, COM1 is spare (as
  you may have your mouse under native DOS there and don't want to
  change the configuration of your modem software between boots of
  native DOS and Linux)

  However, you may use your favorite DOS mousedriver and directly let it
  drive COM1 by changing the below variables (rest of variables
  unchanged)

         $_com1 = "/dev/mouse"
         $_mouse_dev = "com1"

  And finaly, when having a PS2 mouse running on your Linuxbox you use
  the builtin mousedriver (not your mouse.com) to get it work: ( again
  leaving the rest of variables unchanged)

         $_mouse = "ps2"
         $_mouse_dev = "/dev/mouse"

  When using a PS2 mouse or when having more then 2 serial ports you may
  of course assign _any_ free serialdevice to COM1, COM2. The order
  doesn't matter:

         $_com1 = "/dev/cua2"
         $_com2 = "/dev/cua0"

  22..11..1100..  PPrriinntteerrss

  Printer is emulated by piping printer data to your normal Linux
  printer.  The belows tells DOSEMU which printers to use. The `timeout'
  tells DOSEMU how long to wait after the last output to LPTx before
  considering the print job as `done' and to to spool out the data to
  the printer.
       $_printer = "lp"        # list of (/etc/printcap) printer names to appear as
                               # LPT1 ... LPT3 (not all are needed, empty for none)
       $_printer_timeout = (20)# idle time in seconds before spooling out

  22..11..1111..  NNeettwwoorrkkiinngg uunnddeerr DDOOSSEEMMUU

  Turn the following option `on' if you require IPX/SPX emulation, there
  is no need to load IPX.COM within the DOS session.  ( the option does
  not emulate LSL.COM, IPXODI.COM, etc. ) And NOTE: You must have IPX
  protocol configured into the kernel.

         $_ipxsupport = (on)

  Enable Novell 8137->raw 802.3 translation hack in new packet driver.

         $_novell_hack = (on)

  If you make use of the dosnet device driver, you may turn on 'multi'
  packet driver support via

         $_vnet = (on)

  For more on this look at chapter 24 (Net code)

  22..11..1122..  SSoouunndd

  The sound driver is more or less likely to be broken at the moment.
  Anyway, here are the settings you would need to emulate a SB-sound
  card by passing the control to the Linux soundrivers.

       $_sound = (off)           # sound support on/off
       $_sb_base = (0x220)       # base IO-address (HEX)
       $_sb_irq = (5)            # IRQ
       $_sb_dma = (1)            # DMA channel
       $_sb_dsp = "/dev/dsp"     # Path the sound device
       $_sb_mixer = "/dev/mixer" # path to the mixer control
       $_mpu_base = "0x330"      # base address for the MPU-401 chip (HEX)
                                 # (not yet implemented)

  33..  SSeeccuurriittyy

  This part of the document by Hans Lermen, <lermen@fgan.de> on Apr 6,
  1997.

  These are the hints we give you, when running dosemu on a machine that
  is (even temporary) connected to the internet or other machines, or
  that otherwise allows 'foreign' people login to your machine.

  +o  Don't set the -s bit, as of dosemu-0.97.10 DOSEMU can run in
     lowfeature mode without the -s bit set. If you want fullfeatures
     for some of your users, just use the keyword `nosuidroot' in
     /etc/dosemu.users to forbid some (or all) users execution of a suid
     root running dosemu (they may use a non-suid root copy of the
     binary though).

  +o  Use proper file permissions to restrict access to a suid root
     DOSEMU binary in addition to /etc/dosemu.users `nosuidroot'.  (
     double security is better ).

  +o  _N_E_V_E_R let foreign users execute dosemu under root login !!!
     (Starting with dosemu-0.66.1.4 this isn't necessary any more, all
     functionality should also be available when running as user)

  +o  Do _n_o_t configure dosemu with the --enable-runasroot option.
     Normally dosemu will switch privileges off at startup and only set
     them on, when it needs them. With '--enable-runasroot' it would
     permanently run under root privileges and only disable them when
     accessing secure relevant resources, ... not so good.

  +o  Never allow DPMI programms to run, when dosemu is suid root.

     (in /etc/dosemu.conf set 'dpmi off' to disable)

     It is possible to overwrite sensitive parts of the emulator code,
     and this makes it possible for a intruder program under DOS, who
     knows about dosemu interna (what is easy as you have the source) to
     get root access also on non dosemu processes.  Because a lot of
     games won't work without, we allow creation of LDT-descriptor that
     span the whole user space.

     There is a 'secure' option in /etc/dosemu.conf, that allows to turn
     off creation of above mentioned descritors, but those currently
     protect only the dosemu code and the stack, may be some diabolic
     person finds a way to use the (unprotected) heap in his sense of
     humor.

     Anyway, better 'secure on' then nothing.

  +o  Never allow the 'system.com' command (part of dosemu) to be
     executed.  It makes dosemu execute the libc 'system() function'.
     Though privileges are turned off, the process inherits the switched
     uid-setting (uid=root, euid=user), hence the unix process can use
     setreuid to gain root access back. ... the rest you can imagine
     your self. Use of 'system' can be disabled by the 'secure on'
     option in /etc/dosemu.conf

     The 'unix.com' command (also part of dosemu) does _not_ have this
     security hole: before execution a separate process is forked that
     completely drops prililege,

  44..  DDiirreeccttllyy eexxeeccuuttaabbllee DDOOSS aapppplliiccaattiioonnss uussiinngg ddoosseemmuu ((DDEEXXEE))

  This section of the document by Hans, <lermen@fgan.de>. Last updated
  on June 16, 1997.

  44..11..  MMaakkiinngg aanndd UUssiinngg DDEEXXEEss

  Well, you may have wondered what these *.dexe file extension stands
  for.  Looking at the title above you now know it ;-)

  In fact its a tiny hdimage which is bootable and just contains _o_n_e DOS
  application. Because this has isolated access to the hdimage only, it
  may have less security issues then a complete DOS environement under
  Linux and, more worth, you need not to fiddle with installation,
  because the implementor already has done this for you.

  On the other hand, you may create your own *.dexe files using the
  script `mkdexe'. For this to run however you need at least mtools-3.6
  because this versions has options that older versions don't have.

  In detail you need the following to make a *.dexe:

  +o  have _m_t_o_o_l_s_-_3_._6 available.

  +o  have dosemu already compiled _a_n_d did _n_o_t 'make pristine'

  +o  have a *.zip file containing the all files which belong to the DOS
     application (may be whole directories)

  +o  have the following info handy before starting 'mkdexe':

  +o  The partition size needed for the hdimage

  +o  The DOS version that you want to put onto the hdimage.  If your DOS
     app can run under the FreeDos kernel, you don't need that, else
     'mkdexe' needs to know from what bootable existing partition to get
     the system from.

  +o  The contents of the config.sys and autoexec.bat.

  +o  then (as root) do

              # cd ./dexe
              # mkdexe myapp.zip -x myapp.exe -o confirm

  +o  If all went ok, you then have a /var/lib/dosemu/myapp.dexe and this
     one can be executed via

              # dos -L myapp.dex [ dosemu-options ]

  or

              # dosexec myapp.dex [ dosemu-options ]

  Here is what ./mkdexe will print as help, when called without
  argument:

          USAGE:
            mkdexe [{ application | hdimage}]
                               [-b dospart] [{-s|-S} size] [-x appname]
                               [-c confsys] [-a autoexe] [-C comcom ] [-d dosemuconf]
                               [-i IOname] [-m MSname]
                               [-o <option> [-o ...]]

            application  the whole DOS application packet into a *.zip file
            hdimage      the name of the target hdimage, ih -o noapp is give
                         (see below)
            dospart      If not given, FreeDos will be used as system
                         If given it must be either a bootable DOS partion (/dev/...)
                         or a already made bootable dosemu hdimage
            -s size      The _additional_ free space (in Kbytes) on the hdimage
            -S size      The total size (in Kbytes) of the hdimage -s,-S are mutual
                         exclusive.
            appname      The DOS filename of the application, that should be executed
            confsys      Template for config.sys
            autoexe      Template for autoexec.bat
            comcom       file name of the shell, usually command.com
            dosemuconf   Template for the dosemu.conf to use
            IOname       The name of DOS file, that usually is called IO.SYS,
                         (default for FreeDos: IPL.SYS) this one is always put as
                         first file onto the hdimage
            MSname       The name of DOS file, that usually is called MSDOS.SYS,
                         (default for FreeDos: MSDOS.SYS) this one is always put as
                         second file onto the hdimage
            -o <option>  Following option flags are recognized:
                           confirm   offer config.sys, autoexec.bat and dconfig
                                     to edit via $EDITOR
                           nocomcom  Omit command.com, because its not used anyway
                                     when using  shell=c:\appname.exe
                           noapp     Make a simple bootable hdimage for standard
                                     DOSEMU usage (replacement for hdimage.dist)

  If you want to change the builtin configuration file, you may use
  ./src/tools/periph/dexeconfig to extract/re-insert the configuration.

         # dexeconfig -x configfile dexefile

  extracts the configuration out of 'dexefile' and puts it into
  'configfile'

    # dexeconfig -i configfile dexefile

  does the reverse.

  There is a problem, however, when you want allow a user to execute a
  DEXE and the DOS application needs to write to a file within the dexe
  (which is in fact a whole DOS FS). For this would have to give write
  permissions to the user (what is not what you want).  DEXEs have a
  workaround for this: You may set read-only permissions for the DEXE
  file itself in the Linux-FS, but set a flag in the DEXE itself, so
  that DOSEMU will open this file read/write anyway.  This means: The
  user cannot delete or replace the DEXE, but the imbedded DOS-
  application can (totally isolated) write to DOS files within the DEXE
  (complicated, isn't it?). To set such a permission, you (again) need
  `dexeconfig':

         # dexeconfig -p W dexefile

  Here is what 'dexeconfig' will print as help, when called without
  argument:

          USAGE:
             dexeconfig [-M] [-p {w|W}] -i configfile dexefile
             dexeconfig -x configfile dexefile
             dexeconfig -v  dexefile
             dexeconfig -p {w|W}  dexefile

          where is
             -i      insert a config file
             -x      extract a config file
             -p w    clear write permission
             -p W    set write permission
             -v      view status information

  It would be great, if we could collect an archive of working, free
  distributatble *.dexe files, and I'm herein asking for contribution.
  However, _B_I_G _N_O_T_E, if you want to contribute a *.dexe file to the
  public, please do _N_O_T use any other DOS than FreeDos else you would
  violate existing copyrights. This also (unfortunately) is true for
  OpenDos which can only be distributed after Caldera did allow you to
  do so :-(

  If you _h_a_v_e assembled a *.dexe and you wnat to contribute it, please
  send me a mail and upload the stuff to

          tsx-11.mit.edu:/pub/linux/ALPHA/dosemu/Development/Incoming

  I'll then put it into

          tsx-11.mit.edu:/pub/linux/ALPHA/dosemu/dexe/*
          ftp.suse.com:/pub/dosemu/dexe/*

  There currently only is one in that archive: fallout.dexe Its a nice
  Tetris like games that I found on an old CDrom and which runs in
  300x200 on console and X (not Slang-terminal). When you put it into
  you /var/lib/dosemu/* directory, you may start it via:

          dosexec fallout.dexe -X

  Hope we get more of *.dexe in the future ....

  44..22..  UUssiinngg bbiinnffmmtt__mmiisscc ttoo ssppaawwnn DDEEXXEEss ddiirreeccttllyy

  There is a nifty kernel patch flying around from Richard Guenther
  <zxmpm11@student.uni-tuebingen.de>. This can be obtained via

  <http://www.anatom.uni-tuebingen.de/~richi/linux/binfmt_misc.html>

  We hope this patch makes it into the kernel, because then we could
  execute a DEXE just by typing its name at the Bash prompt. To register
  DEXE format using binfmt_misc you do (in your /etc/rc.-whatever)

         cd /proc/sys/fs/binfmt_misc
         echo :DEXE:M::\\x0eDEXE::/usr/bin/dosexec: >register

  thats all.

  44..33..  MMaakkiinngg aa bboooottaabbllee hhddiimmaaggee ffoorr ggeenneerraall ppuurrppoossee

  You may also use './mkdexe' do generate a _normal_ bootable hdimage,
  it then has the advantage, that you no longer need to fiddle with a
  DOS boot disk. I succeded to make a bootable hdimage with FreeDos,
  MSDOS-6.2 and also WINDOWS'95 (yes, that can be booted with the
  DOSEMU-own MBR ;-) I did not test other DOSes, but I guess, they also
  will work, as long as you pass the correct system file names to
  'mkdexe' (-i, -m options)

  Example: Given you have a bootable DOS-partition in /dev/hda1, then
  this ...

    # cd ./dexe
    # ./mkdexe myhdimage -b /dev/hda1 -o noapp

  will generate a direct bootable 'myhdimage' from your existing DOS
  installation. You need not to make a boot floppy, nor need you to
  fiddle with fdisk /MBR and sys.com any more. Using -o confirm you may
  also edit the configuration files before they are put onto the
  hdimage.

  Further more, there is a script on top of mkdexe: setup-hdimage, which
  helps more to firsttime install DOSEMU's hdimage. It prompts for
  needed things and should work on most machines.

         # cd /where/I/have/dosemu
         # ./setup-hdimage

  44..44..  AAcccceessssiinngg hhddiimmaaggee ffiilleess uussiinngg mmttoooollss

  In the ./dexe directory there is also a script, that allows you to
  directly access the hdimage's files, even without changing your
  /etc/mtools.conf. The usage of this script is:

          USAGE:
            do_mtools device mcommand [ arg1 [...] ]

          where is:
            device    = DOS-partition such as '/dev/hda1'
                        or a DOSEMU hdimage
            mcommand  = any valid mtools comand
            argX      = any valid mtools argument.
                        NOTE: for the DOS drive use 'W:'

          example:
            do_mtools /var/lib/dosemu/hdimage mcopy W:/autoexec.bat -

  55..  SSoouunndd

  The SB code is currently in a state of flux. Some changes to the code
  have been made which mean that I can separate the DSP handling from
  the rest of the SB code, making the main case statements simpler. In
  the meantime, Rutger Nijlunsing has provided a method for redirecting
  access to the MPU-401 chip into the main OS.

  55..11..  UUssiinngg tthhee MMPPUU--440011 ""EEmmuullaattiioonn""..

  The Sound driver opens "/var/run/dosemu-midi" and writes the Raw MIDI
  data to this. A daemon is provided which can be can be used to seletc
  the instruments required for use on some soundcards. It is also
  possible to get various instruments by redirecting '/var/run/dosemu-
  midi' to the relevant part of the sound driver eg:
       % ln -s /dev/midi /var/run/dosemu-midi

  This will send all output straight to the default midi device and use
  whatever instruments happen to be loaded.

  55..22..  TThhee MMIIDDII ddaaeemmoonn

         make midid

  This compiles and installs the midi daemon. The daemon currently has
  support for the 'ultra' driver and partial support for the 'OSS'
  driver (as supplied with the kernel) and for no midi system. Support
  for the 'ultra' driver will be compiled in automatically if available
  on your system.

  Copy the executable './bin/midid' so that it is on your path, or
  somewhere you can run it easily.

  Before you run DOSEmu for the first time, do the following:

         mkdir -p ~/.dosemu/run           # if it doesen't exist
         rm -f ~/.dosemu/run/dosemu-midi
         mknod ~/.dosemu/run/dosemu-midi p

  Then you can use the midi daemon like this:

         ./midid < ~/.dosemu/run/dosemu-midi &; dos

  (Assuming that you put the midid executeable in the directory you run
  DOSEmu from.)

  55..33..  DDiissaabblliinngg tthhee EEmmuullaattiioonn aatt RRuunnttiimmee

  You can now disable the code after it is compiled in by setting the
  IRQ or DMA channels to invalid values (ie IRQ = 0 or > 15, or DMA = 4
  or > 7) The simplest way, however, is to say 'sound_emu off' in
  /etc/dosemu.conf

  66..  UUssiinngg LLrreeddiirr

  This section of the document by Hans, <lermen@fgan.de>. Last updated
  on June 16, 1997.

  What is it? Well, its simply a small DOS program that tells the MFS
  (Mach File System) code what 'network' drives to redirect.  With this
  you can 'mount' any Linux directory as a virtual drive into DOS. In
  addition to this, Linux as well as multiple dosemu sessions may
  simultaneously access the same drives, what you can't when using
  partition access.

  66..11..  hhooww ddoo yyoouu uussee iitt??

  First, mount your dos hard disk partition as a Linux subdirectory.
  For example, you could create a directory in Linux such as /dos (mkdir
  -m 755 /dos) and add a line like

          /dev/hda1       /dos     msdos   umask=022

  to your /etc/fstab.  (In this example, the hard disk is mounted read-
  only.  You may want to mount it read/write by replacing "022" with
  "000" and using the -m 777 option with mkdir).  Now mount /dos.  Now
  you can add a line like

         lredir d: linux\fs/dos

  to the AUTOEXEC.BAT file in your hdimage (but see the comments below).
  On a multi-user system you may want to use

         lredir d: linux\fs\${home}

  where "home" is the name of an environmental variable that contains
  the location of the dos directory (/dos in this example)

  However, you may want to have your native DOS partion as C: under
  dosemu.  To reach this aim you also can use Lredir to turn off the
  'virtual' hdimage and switch on the _r_e_a_l drive C: such as this:

  Assuming you have a c:osemu directory on both drives (the virtual and
  the real one) _a_n_d have mounted your DOS partition as /dosc, you then
  should have the following files on the virtual drive:

  autoexec.bat:

         lredir z: linux\fs\dosc
         copy c:\dosemu\auto2.bat z:\dosemu\auto2.bat
         lredir del z:
         c:\dosemu\auto2.bat

  dosemuuto2.bat:

         lredir c: linux\fs\dosc
         rem further autoexec stuff

  To make the reason clear _w_h_y the batch file (not necessaryly
  autoexec.bat) _m_u_s_t be identical:

  Command.com, which interpretes the batchfile keeps a position pointer
  (byte offset) to find the next line within this file. It opens/closes
  the batchfile for _e_v_e_r_y new batchline it reads from it.  If the
  batchfile in which the 'lredir c: ...' happens is on c:, then
  command.com suddenly reads the next line from the batchfile of that
  newly 'redired' drive.  ... you see what is meant?

  66..22..  OOtthheerr aalltteerrnnaattiivveess uussiinngg LLrreeddiirr

  To have a redirected drive available at time of config.sys you may
  either use emufs.sys such as

          device=c:\emufs.sys /dosc

  or make use of the install instruction of config.sys (but not both)
  such as

          install=c:\lredir.exe c: linux\fs\dosc

  The later has the advantage, that you are on your native C: from the
  beginning, _b_u_t, as with autoexec.bat, both config.sys must be
  identical.

  For information on using 'lredired' drives as a 'user' (ie having the
  right permissions), please look at ./doc/README.runasuser.

  77..  RRuunnnniinngg ddoosseemmuu aass aa nnoorrmmaall uusseerr

  This section of the document by Hans, <lermen@fgan.de>. Last updated
  on June 16, 1997.

  1. You have to make 'dos' suid root, if want a fullfeature DOSEMU,
     this normally is done when you run 'make install'.  But as od
     dosemu-0.97.10, you need not if you don't access to ports, external
     DOSish hardware and won't use the console other then in normal
     terminal mode.
  2. You can restrict access to the suid root binary via
     /etc/dosemu.user.  by specifying `nosuidroot' for a given user (or
     all).

  3. Have the users that are allow to execute dosemu in
     /etc/dosemu.user.  The format is:

            loginname [ c_strict ] [ classes ...] [ c_dexeonly ] [ other ]

  For details see ``Configuring DOSEmu''. For a first time _e_a_s_y instal-
  lation you may set it as follows (but don't forget to enhance it later
  !!!):

            root c_all
            lermen c_all
            all nosuidroot c_all

  4. The msdos partitions, that you want to be accessable through
     ``lredir'' should be mounted with proper permissions. I recommend
     doing this via 'group's, not via user ownership. Given you have a
     group 'dosemu' for this and want to give the user 'lermen' access,
     then the following should be

  +o  in /etc/passwd:

            lermen:x:500:100:Hans Lermen:/home/lermen:/bin/bash
                         ^^^-- note: this is NOT the group id of 'dosemu'

  +o  in /etc/group:

            users:x:100:
            dosemu:x:200:dosemu,lermen
                     ^^^

  +o  in /etc/fstab:

            /dev/hda1 /dosc msdos defaults,gid=200,umask=002 0 0
                                               ^^^

  _N_o_t_e_: the changes to /etc/passwd and /etc/group only take place the
  _n_e_x_t time you login, so don't forget to re-login.

  The fstab entry will mount /dosc such that is has the proper permis-
  sions

          ( drwxrwxr-x  22 root     dosemu      16384 Jan  1  1970 /dosc )

  You can do the same with an explicit mount command:

             mount -t msdos -o gid=200,umask=002 /dev/hda1 /dosc

  Of course normal lredir'ed unix directories should have the same per-
  missions.

  5. Make sure you have read/write permissions of the devices you
     configured (in /etc/dosemu.conf) for serial and mouse.

  Starting with dosemu-0.66.1.4 there should be no reason against
  running dosemu as a normal user. The privilege stuff has been
  extensively reworked, and there was no program that I tested under
  root, that didn't also run as user. However, if you suspect problems
  resulting from the fact that you run as user, you should first try
  configuring dosemu with the as (suid) root and only use user
  privileges when accessing secure relevant resources. Normally dosemu
  will permanently run as user and only temporarily use root privilege
  when needed and in case of non-suid root (as of dosemu-0.97.10), it
  will run in lowfeature mode without any priviledges.

  88..  UUssiinngg CCDDRROOMMSS

  88..11..  TThhee bbuuiilltt iinn ddrriivveerr

  This documents the cdrom extension rucker@astro.uni-bonn.de has
  written for Dosemu.

  The driver consists of a server on the Linux side
  (dosemu/drivers/cdrom.c, accessed via int 0xe6 handle 0x40) and a
  device driver (dosemu/commands/cdrom.S) on the DOS side.

  Please send any suggestions and bug reports to <rucker@astro.uni-
  bonn.de>

  To install it:

  +o  Create a (symbolic) link /dev/cdrom to the device file of your
     drive or use the cdrom statement in /etc/dosemu.conf to define it.

  +o  Make sure that you have read/write access to the device file of
     your drive, otherwise you won't be able to use the cdrom under
     Dosemu directly because of security reasons.

  +o  Load cdrom.sys within your config.sys file with e.g.:

           devicehigh=c:\emu\cdrom.sys

  +o  Start Microsoft cdrom extension as follows:

           mscdex /d:mscd0001 /l:driveletter

  To change the cd while Dosemu is running, use the DOS program
  'eject.com'.  It is not possible to change the disk, when the drive
  has been opened by another process (e.g. mounted)!

  Remarks by zimmerma@rz.fht-esslingen.de: This driver has been
  successfully tested with Linux' SCSI CDROMS by the author, with the
  Mitsumi driver mcd.c and with the Aztech/Orchid/Okano/Wearnes- CDROM
  driver aztcd.c by me. With the latter CDROM-drives changing the CD-ROM
  is not recognized correctly by the drive under all circumstances and
  is therefore disabled. So eject.com will not work.  For other CD-ROM
  drives you may enable this feature by setting the variable top of the
  file). With the mcd.c and aztcd.c Linux drivers this may cause your
  system to hang for some 30 seconds (or even indefinitely), so don't
  change the default value 'eject_allowed = 0'.

  History: Release with dosemu.0.60.0 Karsten Rucker (rucker@astro.uni-
  bonn.de) April 1995

  Additional remarks for mcd.c and aztcd.c Werner Zimmermann
  (zimmerma@rz.fht-esslingen.de) May 30, 1995

  99..  LLooggggiinngg ffrroomm DDOOSSEEmmuu

  This section was written by Erik Mouw <J.A.K.Mouw@et.tudelft.nl> on
  February 17, 1996 and last edited on 21 June 1997.

  This section documents the log facilities of DOSEMU.

  DOSEMU is able to log all use with email or syslogd(8).  If you want
  to enable logging, create a file /etc/dosemu.loglevel.  In this file
  you can set the loglevel for both mail and syslog with a very simple
  format. Only four keywords are recognized:

     mmaaiill__eerrrroorr
        mail errors about mis-usage to root

     mmaaiill__aallwwaayyss
        mail all DOSEMU usage to root

     ssyysslloogg__eerrrroorr
        log all errors about mis-usage with syslogd(8)

     ssyysslloogg__aallwwaayyss
        log all DOSEMU usage with syslogd(8)

  A line starting with a '#' is a comment.

  Some samples:

       #
       # mail everything to root, but don't log
       #
       mail_always

       #
       # mail errors to root, log everything
       # (this is the recommended usage)
       #
       mail_error
       syslog_always

       #
       # log errors only
       #
       syslog_errors

  1100..  UUssiinngg XX

  Please read all of this for a more complete X information ;-)

  1100..11..  LLaatteesstt IInnffoo

  From Uwe Bonnes <bon@elektron.ikp.physik.th-darmstadt.de>:

  xdos from dosemu version pre-0.60.4.2 with the patch from my last
  messages should now be more capable.  In particular it should now
  understand the keys from the keypad-area (the keys the most right on a
  MF-Keyboard) and numlock and keyevents in the range of the latin
  characters, even when you run xdos from a remote X-terminal.

  If it dosen't work for you as expected, please check out the
  following:

  +o  Don't specify "keycode" for X-support.  The keycode-option is
     something specific for a special X-server, here XFree86, and so
     isn't portable and I disencourage its use.

  +o  Check out whether your key sends a sensible ksym, with e.g."xev".
     If it sends something sensible which you think should be mapped by
     xdos, please let me know details.

  +o  If you are running xdos on XFree86, version 3.1.1 and newer and the
     keys of the keypad-area don't work, you have two options:

  +o  Comment out the line "    ServerNumLock " in
     /usr/X11R6/lib/X11/XFConfig

  +o  Feed the following file to xmodmap. From what I understand from the
     docs, XFree-3.1.1 should do that intrinsicly, but for me it didn't.
     This is a part of the file /usr/X11R6/lib/X11/etc/xmodmap.std

       ! When using ServerNumLock in your XF86Config, the following codes/symbols
       ! are available in place of 79-81, 83-85, 87-91
       keycode  136 = KP_7
       keycode  137 = KP_8
       keycode  138 = KP_9
       keycode  139 = KP_4
       keycode  140 = KP_5
       keycode  141 = KP_6
       keycode  142 = KP_1
       keycode  143 = KP_2
       keycode  144 = KP_3
       keycode  145 = KP_0
       keycode  146 = KP_Decimal
       keycode  147 = Home
       keycode  148 = Up
       keycode  149 = Prior
       keycode  150 = Left
       keycode  151 = Begin
       keycode  152 = Right
       keycode  153 = End
       keycode  154 = Down
       keycode  155 = Next
       keycode  156 = Insert
       keycode  157 = Delete

  1100..22..  SSlliigghhttllyy oollddeerr iinnffoorrmmaattiioonn

  From Rainer Zimmermann <zimmerm@mathematik.uni-marburg.de>

  Some basic information about dosemu's X support.  Sometimes it's even
  sort of useable now.

  What you should take care of:

  +o  Do a 'xmodmap -e "keycode 22 = 0xff08"' to get use of your
     backspace key.

  +o  Do a 'xmodmap -e "keycode 107 = 0xffff"' to get use of your delete
     key.

  +o  Make sure dosemu has X support compiled in.  (X_SUPPORT = 1 in the
     Makefile)

  +o  you should have the vga font installed. See README.ncurses.

  +o  start dosemu with 'dos -X' from an X terminal window.  Or make a
     link to 'dos' named 'xdos' - when called by that name, dosemu will
     automatically assume -X.  There is also a new debug flag 'X' for X-
     related messages.  To exit xdos, use 'exitemu' or select 'Close'
     aka 'Delete' (better not 'Destroy') from the 'Window' menu.

  +o  there are some X-related configuration options for dosemu.conf.
     See examples/config.dist for details.

  +o  starting xdos in the background (like from a window manager menu)
     appears not to work for some reason.
  +o  Keyboard support in the dosemu window isn't perfect yet. It
     probably could be faster, some key combos still don't work (e.g.
     Ctrl-Fn), etc.  However, input through the terminal window (i.e.
     the window you started dosemu from) is still supported. If you have
     problems, you *might* be better off putting your focus in there.

  +o  Keyboard support of course depends on your X keyboard mappings
     (xmodmap).  If certain keys don't work (like Pause, Backspace,...),
     it *might* be because you haven't defined them in your xmodmap, or
     defined to something other than dosemu expects.

  +o  using the provided icon (dosemu.xpm):

  +o  you need the xpm (pixmaps) package. If you're not sure, look for a
     file like /lib/libXpm.so.*

  +o  you also need a window manager which supports pixmaps. Fvwm is
     fine, but I can't tell you about others. Twm probaby won't do.

  +o  copy dosemu.xpm to where you usually keep your pixmap (not bitmap!)
     files (perhaps /usr/include/X11/pixmaps)

  +o  tell your window manager to use it. For fvwm, add the following
     line to your fvwmrc file:

            Icon "xdos"   dosemu.xpm

  This assumes you have defined a PixmapPath. Otherwise, specify the
  entire pathname.

  +o  note that if you set a different icon name than "xdos" in your
     dosemu.conf, you will also have to change the fvwmrc entry.

  +o  restart the window manager. There's usually an option in the root
     menu to do so.

     Now you should see the icon whenever you iconify xdos.

     Note that the xdos program itself does not include the icon -
     that's why you have to tell the window manager. I chose to do it
     this way to avoid xdos _r_e_q_u_i_r_i_n_g the Xpm library.

  +o  If anything else does not work as expected, don't panic :-)
     Remember the thing is still under construction.  However, if you
     think it's a real bug, please tell me.

  important changes to previous version (pre53_17):

  +o  fixed focus handling at startup

  +o  support for 21/28/43/50 line modes!  (43+50 look a bit funny,
     though... I use the 8x16 font for all modes)

  +o

  +o  fixed startup error handling (won't hang now if display not found)

  +o  limited window size

  1100..33..  SSttaattuuss ooff XX ssuuppppoorrtt ((SSeepptt 55,, 11999944))

  1100..33..11..  DDoonnee

  +o  X_update_screen    (video output)

  +o  implement cursor

  +o  fix cursor/scrolling bugs

  +o  fix Scroll (video/terminal.c) (?)

  +o  fix banner message (initialization) (works after video cleanup,
     dunno why :)

  +o  check video memory dirty bit

  +o  X event handling   (close, expose, focus etc.)

  +o  fixed cursor initialization

  +o  cleaned up cursor handling

  +o  added 'xdos' calling method

  +o  disable 'mouse' serial ports in X mode

  +o  write direct scroll routine (not used yet, though)

  +o  care about int10 calls  -ok?

  +o  Handle close ("delete") window event - (copied from xloadimage)

  +o  X keyboard support (pcemu code, heavily modified)

  +o  Mouse support

  +o  X configuration (display, updatefreq, updatelines,... what else?)

  +o  int10 video mode switches (resize window)

  +o  Window SizeHints  (fixed size or max size?)

  +o  create icon :-)

  1100..33..22..  TTooDDoo ((iinn nnoo ssppeecciiaall oorrddeerr))

  +o  xor cursor? blinking cursor?

  +o  use mark's scroll detector

  +o  jump scroll?

  +o  fine-tune X_update_screen

  +o  graphics support?

  +o  allow non-standard font heights via bios

  +o  cut & paste

  1100..44..  TThhee aappppeeaarraannccee ooff GGrraapphhiiccss mmooddeess ((NNoovveemmbbeerr 1133,, 11999955))

  Erik Mouw <J.A.K.Mouw@et.tudelft.nl> & Arjan Filius
  <I.A.Filius@et.tudelft.nl>

  We've made some major changes in X.c that enables X to run graphics
  modes.  Unfortunately, this disables the cut-and-paste support, but we
  think the graphics stuff is much more fun (after things have
  established, we'll put the cut-and-paste stuff back). The graphics is
  done through vgaemu, the VGA emulator. Status of the work:

  1100..44..11..  vvggaaeemmuu

  +o  Video memory. 1 Mb is allocated. It is mapped with mmap() in the
     VGA memory region of dosemu (0xa00000-0xbfffff) to support bank
     switching.  This is very i386-Linux specific, don't be surprised if
     it doesn't work under NetBSD or another Linux flavour
     (Alpha/Sparc/MIPS/etc).

  +o  The DAC (Digital to Analog Converter). The DAC is completely
     emulated, except for the pelmask. This is not difficult to
     implement, but it is terribly slow because a change in the pelmask
     requires a complete redraw of the screen. Fortunately, the pelmask
     changes aren't used often so nobody will notice ;-)

  +o  The attribute controller is partially emulated. (Actually, only
     reads and writes to the ports are emulated)

  +o  The working modes are 0x13 (320x200x256) and some other 256 color
     modes.

  +o  To do (in no particular order): font support in graphics modes
     (8x8, 8x16, 9x16, etc), text mode support, 16, 4 and 2 color
     support, better bank switching, write the X code out of vgaemu to
     get it more generic.

  1100..44..22..  vveessaa

  +o  VESA set/get mode, get information and bankswitch functions work.

  +o  All VESA 256 color (640x480, 800x600, 1024x768) modes work, but due
     to bad bank switch code in vgaemu they won't display right.

  +o  A VESA compatible video BIOS is mapped at 0xc00000. It's very
     small, but in future it's a good place to store the BIOS fonts
     (8x8, 8x16) in.

  +o  To do: implement the other VESA functions.

  1100..44..33..  XX

  +o  Added own colormap support for the 256 color modes.

  +o  Support for vgaemu.

  +o  Some cleanups.

  +o  To do: remove text support and let vgaemu do the text modes, put
     back the cut-and-paste stuff, more cleanups.

  +o  _N_O_T_E_: we've developed on X servers with 8 bit pixel depths
     (XF86_SVGA) so we don't know how our code behaves on other pixel
     depths. We don't even know if it works.

  As stated before, this code was written for Linux (tested with 1.2.13
  and 1.3.39) and we don't know if it works under NetBSD. The mmap() of
  /proc/self/mem and mprotect() magic in vgaemu are very (i386) Linux
  specific.

  Erik

  1100..55..  TThhee nneeww VVGGAAEEmmuu//XX ccooddee ((JJuullyy 1111,, 11999977))

  Steffen Winterfeldt <Steffen.Winterfeldt@itp.uni-leipzig.de>

  I've been working on the X code and the VGA emulation over the last
  few months. This is the outcome so far:

  +o  graphics support in X now works on all X servers with color depth
     >= 8

  +o  the graphics window is resizeable

  +o  support for hi- and true-color modes (using Trident SVGA mode
     numbers and bank switching)

  +o  some basic support for mode-X type graphics modes (non-chain4 modes
     as used by e.g. DOOM)

  +o  some even more basic support for 16 color modes

  +o  nearly full VESA 2.0 support

  +o  gamma correction for graphics modes

  +o  video memory size is configurable via dosemu.conf

  +o  initial graphics window size is configurable

  The current implementation supports 4 and 8 bit SVGA modes on all
  types of X display. Hi-color modes are supported only on displays
  matching the exact color depth (15 or 16); true color modes are
  supported only on true color X displays, but always both 24 bit and 32
  bit SVGA modes.

  In addition, the current hi- and true color support does not allow
  resizing of the graphics window and gamma correction is ignored.

  As the typical graphics mode with 320x200x8 will be used often with
  large scalings and modern graphics boards are pretty fast, I added
  something to eat up your CPU time: you can turn on the bilinear
  interpolation. It greatly improves the display quality (but is rather
  slow as I haven't had time yet to implement an optimized version -
  it's plain C for now).  If the bilinear filter is too slow, you might
  instead try the linear filter which interpolates only horizontally.

  Note that (bi)linear filtering is not available on all VGA/X display
  combinations. The standard drawing routines are used instead in such
  cases.

  If a VGA mode is not supported on your current X display, the graphics
  screen will just remain black. Note that this ddooeess nnoott mean that xdos
  has crashed.

  The VESA support is (or should be) nearly VBE 2.0 compatible. As a
  reference I used several documents including the unofficial VBE 2.0
  specs made available by SciTech Software. I checked this against some
  actual implementations of the VBE 2.0 standard, including SciTech's
  Display Doctor (formerly known as UniVBE).  Unfortunately
  implementations and specs disagree at some points.  In such cases I
  assumed the actual implementation to be correct.

  The only unsupported VBE function is VGA state save/restore. But this
  functionality is rarely used and its lack should not cause too much
  problems.

  VBE allows you to use the horizontal and vertical scrolling function
  even in text modes. This feature is not implemented.

  If you think it causes problems, the linear frame buffer (LFB) can be
  turned of via dosemu.conf as well as the protected mode interface.
  Note, however, that LFB modes are faster than banked modes, even in
  DOSEmu.

  The default VBE mode list defines a lot of medium resolution modes
  suitable for games (like Duke3D). You can still create your own modes
  via dosemu.conf. Note that you cannot define the same mode twice; the
  second (and all subsequent) definitions will be ignored.

  Modes that are defined but cannot be supported due to lack of video
  memory or because they cannot be displayed on your X display, are
  marked as unsupported in the VBE mode list (but are still in it).
  Note that there is currently no support of 4 bit VESA modes.

  The current interface between VGAEmu and X will try to update all
  invalid video pages at a time. This may, particularly in hi-res
  VBE/SVGA modes, considerably disturb DOSEmu's signal handling. That
  cannot be helped for the moment, but will be addressed soon (by
  running an extra update thread).

  If you really think that this is the cause of your problem, you might
  try to play with veut.max_max_len in env/video/n_X.c, near line 2005.
  This variable limits the amount of video memory that is updated during
  one timer interrupt. This way you can dramatically reduce the load of
  screen updates, but at the same rate reduce your display quality.

  Gamma correction works in both 4 and 8 bit modes. As the dosemu.conf
  parser doesn't support float values, it must be specified as a
  percentage value: gamma 100 = gamma 1.0. Higher values give brighter
  graphics, lower make them darker. Reasonable values are within a range
  of 50 ... 200.

  You can specify the video memory size that the VGA emulator should use
  in dosemu.conf. The value will be rounded up to the nearest 256 kbyte
  boundary. You should stick to typical values like 1024, 2048 or 4096
  as not to confuse DOS applications.  Note that whatever value you
  give, 4 bit modes are only supported up to a size of 800x600.

  You can influence the initial size of the graphics window in various
  ways. Normally it will have the same size (in pixel) as the VGA
  graphics mode, except for mode 0x13 (320x200, 256 colors), which will
  be scaled by the value of _m_o_d_e_1_3_f_a_c_t (defaults to 2).  Alternatively,
  you can directly specify a window size in dosemu.conf via _w_i_n_s_i_z_e. You
  can still resize the window later.

  The config option _f_i_x_e_d___a_s_p_e_c_t allows you to fix the aspect ratio of
  the graphics window while resizing it. Alternatively, _a_s_p_e_c_t___4_3 ties
  the aspect ratio to a value of 4:3. The idea behind this is that,
  whatever the actual resolution of a graphics mode is in DOS, it is
  displayed on a 4:3 monitor. This way you won't run into problems with
  modes such as 640x200 (or even 320x200) which would look somewhat
  distorted otherwise.

  1111..  RRuunnnniinngg WWiinnddoowwss uunnddeerr DDOOSSEEmmuu

  Okay, perhaps you've heard the hooplah.  DOSEMU can run Windows (sort
  of.)

  1111..11..  WWiinnddoowwss 33..00 RReeaall MMooddee

  DOSEMU has been able to run Windows 3.0 in Real Mode for some time
  now.  If you really, really, really want to run Windows under DOSEMU,
  this is the route to take for the moment.

  1111..22..  WWiinnddoowwss 33..11 PPrrootteecctteedd MMooddee

  ***************************************************************
  *    WARNING!!! WARNING!!! WARNING!!! WARNING!!! WARNING!!!   *
  *                                                             *
  *  Danger Will Robinson!!!  This is not yet fully supported   *
  *  and there are many known bugs!  Large programs will almost *
  *  certainly NOT WORK!!!  BE PREPARED FOR SYSTEM CRASHES IF   *
  *  YOU TRY THIS!!!                                            *
  *                                                             *
  *    WARNING!!! WARNING!!! WARNING!!! WARNING!!! WARNING!!!   *
  ***************************************************************

  What, you're still reading?

  Okay, it is possible to boot WINOS2 (the modified version of Windows
  3.1 that OS/2 uses) under DOSEMU.  Many kudos to Lutz & Dong!

  However, YOU NEED BBOOTTHH LICENSES, for WINDOWS-3.1 as well OS/2 !!!

  There are many known problems.  Windows is prone to crash, could take
  data with it, large programs will not load, etc. etc. etc.  In other
  words, it is NOT ready for daily use.  Many video cards are known to
  have problems (you may see a nice white screen, however, look below
  for win31-in-xdos).  Your program groups are all likely to disappear.
  Basically, it's a pain.

  On the other hand, if you're dying to see the little Windows screen
  running under Linux and you have read this CAREFULLY and PROMISE NOT
  TO BOMBARD THE DOSEMU DEVELOPERS WITH "MS Word 6.0 doesn't run!!!"
  MESSAGES

  +o  Get DOSEMU & the Linux source distributions.

  +o  Unpack DOSEMU.

  +o  Configure DOSEMU typing './configure' and do _not_ disable
     vm86plus.

  +o  Compile DOSEMU typing 'make'.

  +o  Get the OS2WIN31.ZIP distribution from  ????  oh well, and now you
     have the first problem.  It _was_ on ibm.com sometime ago, but has
     vanished from that site, and as long as it was there, we could
     mirror it. ,,,, you see the problem?  However, use 'archie' to find
     it, it will be around somewhere on the net ,,, for some time ;-)

  +o  Unpack the OS2WIN31 files into your WINDOWSTEM directory.  (Infact
     you only need WINDOWS/SYSTEM/os2k386.exe and the mouse driver)

  +o  Startup dosemu (make certain that DPMI is set to a value such as
     4096)

  +o  Copy the file winemu.bat to your c: drive.

  +o  Cross your fingers.

  Good luck!

  RREEMMEEMMBBEERR::  TTHHIISS IISS NNOOTT AATT AALLLL RREECCOOMMMMEENNDDEEDD!!!!!!  TTHHIISS IISS NNOOTT
  RREECCOOMMMMEENNDDEEDD!!!!!!  WWEE DDOO NNOOTT RREECCOOMMMMEENNDD YYOOUU TTRRYY TTHHIISS!!!!!!

  1111..33..  WWiinnddoowwss 33..xx iinn xxddooss

  As of version 0.64.3 DOSEMU is able to run Windows in xdos. Of course,
  this is not recommended at all, but if you really want to try, it is
  safer then starting windows-31 on the console, because _w_h_e_n it
  crashes, it doesn't block your keyboard or freeze your screen.

  Hints:

  +o  Get Dosemu & Linux source.

  +o  Unpack dosemu.

  +o  Run "./configure" to configure Dosemu (it will enable vm86plus as a
     default).

  +o  Type "make" to compile.

  +o  Get a Trident SVGA drivers for Windows. The files are tvgaw31a.zip
     and/or tvgaw31b.zip. They are available at garbo.uwasa.fi in
     /windows/drivers (any mirrors?).

  +o  Unpack the Trident drivers.

  +o  In Windows setup, install the Trident "800x600 256 color for 512K
     boards" driver.

  +o  Do the things described above to get and install OS2WIN31.

  +o  Start xdos.

  +o  In Dosemu, go to windows directory and start winemu.

  +o  Cross your fingers.

  Notes for the mouse under win31-in-xdos:

  +o  In order to let the mouse properly work you need the following in
     your win.ini file:

            [windows]
            MouseThreshold1=0
            MouseThreshold2=0
            MouseSpeed=0

  +o  The mouse cursor gets not painted by X, but by windows itself, so
     it depends on the refresh rate how often it gets updated, though
     the mouse coordinates movement itself will not get delayed.  ( In
     fact you have 2 cursors, but the X-cursor is given an 'invisible'
     cursor shape while within the DOS-Box. )

  +o  Because the coordinates passed to windows are interpreted
     relatively, we need to calibrate the cursor. This is done
     automatically whenever you enter the DOS-Box window: The cursor
     gets forced to 0,0 and then back to its right coordinates. Hence,
     if you want to re-calibrate the cursor, just move the cursor
     outside and then inside the DOS-Box again.
  1122..  MMoouussee GGaarrrroott

  This section, and Mouse Garrot were written by Ed Sirett
  <ed@cityscape.co.uk> on 30 Jan 1995.

  Mouse Garrot is an extension to the Linux Dos Emulator that tries to
  help the emulator give up CPU time to the rest of the Linux system.

  It tries to detect the fact the the mouse is not doing anything and
  thus to release up CPU time, as is often the case when a mouse-aware
  program is standing idle, such programs are often executing a loop
  which is continually checking the mouse buttons & position.

  Mouse Garrot is built directly into dosemu _i_f _a_n_d _o_n_l_y _i_f you are
  using the internal mouse driver of dosemu. All you have to do is make
  sure that the HOGTHRESHOLD value in the config file is non-zero.

  If you are loading a (DOS based) mouse driver when you boot then you
  will also need to load MGARROT.COM It is essential that you load
  MGARROT.COM _a_f_t_e_r you load the mouse driver. MGARROT will tell you if
  you are (a) running real DOS not dosemu, or (b) have requested a zero
  value for the HOGTHRESHOLD in the config file. In either case MGARROT
  fails to install and no memory will be lost. When MGARROT is installed
  it costs about 0.4k.  MGARROT may loaded `high' if UMBs are available.

  Mouse Garrot will work with many (maybe most) mouse-aware programs
  including Works, Dosshell and the Norton Commander.  Unfortunately,
  there are some programs which get the mouse driver to call the program
  whenever the mouse moves or a button is pressed. Programs that work in
  this way are immune to the efforts of Mouse Garrot.

  1133..  RRuunnnniinngg aa DDOOSS--aapppplliiccaattiioonn ddiirreeccttllyy ffrroomm UUnniixx sshheellll

  This part of the document was written by Hans <lermen@fgan.de>.

  1133..11..  UUssiinngg tthhee kkeeyyssttrrookkee aanndd ccoommmmaannddlliinnee ooppttiioonnss..

  Make use of the keystroke configure option and the -I commandline
  option of DOSEMU (>=dosemu-0.66.2) such as

       dos -D-a -I 'keystroke "dir > C:\\garbage\rexitemu\r"'

  The "..." will be 'typed in' by dosemu exactly as if you had them
  typed at the keyboard. The advantage of this technique is, that all
  DOS applications will accept them, even interactive ones. A '' is
  interpreted as in C and leads in ESC-codes. Here a list of of the
  current implemented ones:

  \r     Carriage return == <ENTER>
  \n     LF
  \t     tab
  \b     backspace
  \f     formfeed
  \a     bell
  \v     vertical tab

  \^x    <Ctrl>x, where X is one of the usual C,M,L,[ ...
         (e.g.: \^[ == <Ctrl>[ == ESC )

  \Ax    <Alt>x, hence  \Ad means <Alt>d

  \Fn;   Function key Fn. Note that the trailing ';' is needed.
         (e.g.:  \F10;  == F10 )

  \Pn;   Set the virtual typematic rate, thats the speed for
         autotyping in. It is given in unix timer ticks to wait
         between two strokes. A value of 7 for example leads to
         a rate of 100/7=14 cps.

  \pn;   Before typing the next stroke wait n unix ticks.
         This is usefull, when the DOS-application fushes the
         keybord buffer on startup. Your strokes would be discared,
         if you don't wait.

  When using X, the keystroke feature can be used to directly fire up a
  DOS application with one click, if you have the right entry in your
  .fvwmrc

  1133..22..  UUssiinngg aann iinnppuutt ffiillee

  +o  Make a file "FILE" containing all keystrokes you need to boot
     dosemu and to start your dos-application, ... and don't forget to
     have CRLF for 'ENTER'. FILE may look like this (as on my machine):

            2^M                    <== this chooses point 2 of the boot menu
            dir > C:\garbage^M     <== this executes 'dir', result to 'garbage'
            exitemu^M              <== this terminates dosemu

  (the ^M stands for CR)

  +o  execute dosemu on a spare (not used) console, maybe /dev/tty20 such
     like this:

          # dos -D-a 2>/dev/null <FILE >/dev/tty20

  This will _not_ switch to /dev/tty20, but silently execute dosemu and
  you will get the '#' prompt back, when dosemu returns.

  I tested this with dosemu-0.64.4/Linux-2.0.28 and it works fine.

  When your dos-app does only normal printout (text), then you may even
  do this

          # dos -D-a 2>/dev/null <FILE >FILE.out

  FILE.out then contains the output from the dos-app, but merged with
  ESC-sequences from Slang.

  You may elaborate this technique by writing a script, which gets the
  dos-command to execute from the commandline and generate 'FILE' for
  you.

  When you try to use one of the above to start dosemu out of a crontab,
  then you have to asure, that the process has a proper environement set
  up ( especially the TERM and/or TERMCAP variable ).

  1144..  SSeettttiinngg HHooggTThhrreesshhoolldd

  Greetings DOSEMU fans,

  Hogthreshold is a value that you may modify in your DOSEMU.CONF file.
  It is a measure of the "niceness" of Dosemu.  That is to say, it
  attempts to return to Linux while DOS is 'idling' so that DOSEMU does
  not hog all the CPU cycles while waiting at the DOS prompt.

  Determining the optimal Hogthreshold value involves a little bit of
  magic (but not so much really.)  One way is to try different values
  and look at the 'top' reading in another console.  Setting the value
  too low may mildly slow Dosemu performance.  Setting the value too
  high will keep the idling code from working.

  That said, a good basic value to try is "half of your Bogo-Mips
  value".  (The Bogo-Mips value is displayed when the kernel is booting,
  it's an imaginary value somewhat related to CPU performance.)

  Setting the value to 0 will disable idling entirely.  The default
  value is 10.

  This files is some kind of FAQ on how to use the 'HogThreshold' value
  in the dosemu config file.

  In case you have more questions feel free to ask me (
  <andi@andiunx.m.isar.de>).

  Those of you who simply want to have DOSEMU running at highest
  possible speed simply leave the value to zero, but if you are
  concerned about DOSEMU eating too much CPU time it's worth playing
  with the HogThreshold value.

     WWhhyy ddoo II nneeeedd ttoo sseett tthhee HHooggTThhrreesshhoolldd vvaalluuee,, wwhhyy ccaann''tt DDOOSSEEMMUU
        just stop if it is waiting for a keystroke ?"  The reason is the
        way how DOS and a lot of applications have implemented `waiting
        for a keystroke'.

        It's most often done by something similar to the following code
        fragment :

          wait_for_key:
                  ; do something
                  mov ah,1
                  int 0x16 ; check key status
                  jz      wait_for_key ; jump if no key
                  ; found a key
                  mov ah,0
                  int 0x16 ; get key

     This means that the application is busy waiting for the keystroke.

     WWhhaatt iiss aa ggoooodd vvaalluuee ffoorr HHooggTThhrreesshhoolldd ttoo ssttaarrtt wwiitthh ??
        On a 40 MHZ 486 start with a value of 10.  Increase this value
        if you to have your DOS application run faster, decrease it if
        you think too much CPU time is used.

     IItt ddooeess nnoott wwoorrkk oonn mmyy mmaacchhiinnee..
        You need to have at least dosemu0.53pl40 in order to have the
        anti-hog code in effect.

     WWhhyy nnoott ssiimmppllyy uussee aa vveerryy llooww vvaalluuee ooff
        Do I really have to try an individual value of HogThreshold ?"
        This would slow down your DOS application. But why not, DOS is
        slow anyway :-).

     HHooww ddoo II ffoouunndd oouutt aabboouutt CCPPUU uussaaggee ooff DDOOSSEEMMUU ??
        Simply use `top'. It displays cpu and memory usage.

  P.S.  If you want to change the HogThreshold value during execution,
  simply call

        mov al,12h
        mov bx,the_new_value
        int e6h

  This is what speed.com does. If you are interested, please take a look
  at speed.c.

  Notes:  If your application is unkind enough to do waits using an
  int16h fcn 1h loop without calling the keyboard idle interrupt (int
  28h), this code is not going to help much.  If someone runs into a
  program like this, let me ( <scottb@eecs.nwu.edu> ) know and I'll
  rewrite something into the int16 bios.

  1155..  CCoommmmaannddss && UUttiilliittiieess

  These are some utitlies to assist you in using Dosemu.

  1155..11..  PPrrooggrraammss

     bboooottooffff..ccoomm
        switch off the bootfile to access disk see examples/config.dist
        at bootdisk option

     bboooottoonn..ccoomm
        switch on the bootfile to access bootfile see
        examples/config.dist at bootdisk option

     cchhddiirr..ccoomm
        change the Unix directory for Dosemu (use chdir(2))

     ddoossddbbgg..ccoomm
        change the debug setting from within Dosemu

     +o  dosdbg -- show current state

     +o  dosdbg <string>

     +o  dosdbg help -- show usage information

     dduummppccoonnff..eexxee
        ???

     eejjeecctt..ccoomm
        eject CD-ROM from drive

     eemmuummoouussee..ccoomm
        fine tune internal mousedriver of Dosemu

     +o  emumouse h -- display help screen

     eexxiitteemmuu..ccoomm
        terminate Dosemu

     ggeettccwwdd..ccoomm
        get the Unix directory for Dosemu (use getcwd(2))

     iisseemmuu..ccoomm
        detects Dosemu version and returns greater 0 if running under
        Dosemu

     llaanncchheecckk..eexxee
        ???

     llrreeddiirr..ccoomm
        redirect Linux directory to Dosemu
     +o  lredir -- show current redirections

     +o  lredir D: LINUXFSmp -- redirects /tmp to drive D:

     +o  lredir help -- display help screen

     mmggaarrrroott..ccoomm
        give up cpu time when Dosemu is idle

     ssppeeeedd..ccoomm
        set cpu usage (HogThreshold) from inside Dosemu

     ssyysstteemm..ccoomm
        interface to system(2)...

     uunniixx..ccoomm
        execute Unix commands from Dosemu

     +o  unix -- display help screen

     +o  unix ls -al -- list current Linux directory

     +o  caution! try "unix" and read the help screen

     ccmmddlliinnee..eexxee
        Read /proc/self/cmdline and put strings such as "var=xxx" found
        on the commandline into the DOS enviroment.  Example having this
        as the dos commandine:

                           dos "autoexec=echo This is a test..."

     then doing

                           C:\cmdline < D:\proc\self\cmdline
                           %autoexec%

     would display "This is a test..." on the DOS-Terminal

     vvggaaooffff..ccoomm
        disable vga option

     vvggaaoonn..ccoomm
        enable vga option

  1155..22..  DDrriivveerrss

  These are useful drivers for Dosemu

     ccddrroomm..ssyyss
        allow direct access to CD-ROM drives from Dosemu

     eemmss..ssyyss
        enable EMM in Dosemu

     eemmuuffss..ssyyss
        redirect Unix directory to Dosemu

  1166..  KKeeyymmaappss

  This keymap is for using dosemu over telnet, and having *all* your
  keys work.  This keymap is not complete.  But hopefully with everyones
  help it will be someday :)

  There are a couple of things that are intentionally broken with this
  keymap, most noteably F11 and F12.  This is because they are not
  working though slang correctly at the current instant.  I have them
  mapped to "greyplus" and "greyminus".  Also the scroll lock is mapped
  to shift-f3.  This is because the scroll lock dosn't work right at
  all.  Please feel free to send keymap patches in that fix anything but
  these.

  If you want to patch _d_o_s_e_m_u to fix either of those problems, i'd be
  _g_l_a_d to accept those :)

  to figure out how to edit this, read the keystroke-howto.

  as of 3/30/95, control/shift/alternate
  home/insert/delete/end/pageup/pagedown should work.

  Major issues will be:

  Do we move "alt-<fkey>" to "control-<fkey>" to switch virtual
  consoles?

  who is going to fix the linux keyboard device to be able to handle
  multiple keymaps at the same time?

  --------------------------------------------------------

  to use it:

  as root type

               loadkeys dosemu.new.keymap

  (then run dosemu via telnet, or something in slang mode)

  when your done, find your old keymap, and load it back, cause control-
  home won't work in emacs anymore (or any other special key in any
  applicaion that uses xlate)

  if you find a key missing, please add it and send me the patch.  (test
  it first! :)

  if you find a key missing, and don't feel like coding it, _d_o_n_'_t _t_e_l_l
  _m_e!  I already know that there are a lot of keys missing.

  corey sweeney <corey@interaccess.com >

  Sytron Computers

  1177..  NNeettwwoorrkkiinngg uussiinngg DDOOSSEEmmuu

  A mini-HOWTO from Bart Hartgers <barth@stack.nl> ( for the detailed
  original description see below )

  1177..11..  TThhee DDOOSSNNEETT vviirrttuuaall ddeevviiccee..

  Dosnet.o is a kernel module that implements a special virtual network
  device. In combination with pktdrv.c and libpacket.c, this will enable
  multiple dosemu sessions and the linux kernel to be on a virtual
  network. Each has it's own network device and ethernet address.

  This means that you can telnet or ftp from the dos-session to your
  telnetd/ftpd running in linux and, with IP forwarding enabled in the
  kernel, connect to any host on your network.

  1177..22..  SSeettuupp ffoorr vviirrttuuaall TTCCPP//IIPP

  Go to ./src/dosext/net/v-net and make dosnet.o. As root, insmod
  dosnet.o. Now as root, configure the dsn0 interface (for example:
  ifconfig dsn0 192.168.74.1 netmask 255.255.255.0), and add a route for
  it (for example: route add -net 192.168.74.0 netmask 255.255.255.0
  dsn0).

  Finally, start dosemu, and give your TCP/IP client and ip-address in
  the subnet you just configured. This address should be unique, i.e. no
  other dosemu, or the kernel, should have this address. For the example
  addresses given above, 192.168.74.2-192.168.74.254 would be good. Now
  you can use a dos telnet client to telnet to your own machine!

  1177..33..  FFuullll DDeettaaiillss

  Modified description of Vinod G Kulkarni <vinod@cse.iitb.ernet.in>

  Allowing a program to have its own network protocol stacks.

  Resulting in multiple dosemu's to use netware, ncsa telnet etc.

  1177..33..11..  IInnttrroodduuccttiioonn

  Allowing network access from dosemu is an important functionality.
  For pc based network product developers, it will offer an easy
  development environment will full control over all the traffic without
  having to run around and use  several machines.  It will allow already
  available client-server based "front-ends" to run on dosemulator.
  (Assuming that they are all packet driver based -- as of now ;-) )

  To accomplish that, we require independent protocol stacks to coexist
  along with linux' IP stack. One way is to add independent network
  card.  However, it is cumbersome and allows at most only 2-3 stacks.
  Other option is to use the a virtual network device that will route
  the packets to the actual stacks which run as user programs.

  1177..33..22..

  DDeessiiggnn

  Have a virtual device which provides  routing interface at one end (so
  it is a network device from linux side) and at other end, it
  sends/receives packets from/to user stacks.

  All the user stacks AND virtual device are virtually connected by a
  network (equavalent to a physical cable). Any broadcast packet (sent
  by either user stack or router interface of the virtual device) should
  be sent to all the user stacks and router.  All non-broadcast packets
  can be sent by communicating with each other.

  Each user stack (here dosemu process) will have an base interface
  which allows sending and receiving of packets. On the top of this, a
  proper interface (such as  packet driver interface) can be built.  In
  dosemu, a packet driver interface is emulated.

  Every user stack will have a unique  virtual ethernet address.

  1177..33..33..  IImmpplleemmeennttaattiioonn

  This package includes:

  1. dosnet module. Acts as virtual network device introducing It
     provides usual network interface AND also facility to communicate
     with dosemu's.

  2. Modified  packet driver code (pktnew.c and libdosemu.c) to enable
     the above. Modifications include these:

     a. Generate an unique ethernet address for each dosemu .  I have
        used minor no. of the tty in use as part of ethernet address.
        This works unless you start two dosemu's in same tty.

     b. Communication with dosnet device is done by opening a
        SOCK_PACKET socket of special type.

  3. IPX bridge code. Between eth0 and dsn0 so that multiple lan
     accesses can be made. 0.1 is non-intelligent.  (both versions are
     alpha codes.)  Actually IPX routing code is there in kernel.  Has
     anyone been successful in using this?  Yet another alternative is
     to use IPTunnelling of IPX packets (rfc 1234). Novell has NLMs for
     this on the netware side. On linux, we should run a daemon
     implementing this rfc.

  1177..33..44..  VViirrttuuaall ddeevviiccee ''ddssnn00''

  Compile the module dosnet and insmod it, and give it an IP address,
  with a new IP network number. And You have to set up proper routing
  tables on all machines you want to connect to.  So linux side
  interface is easy to set up.

  This device is assigned a virtual ethernet address, defined in
  dosnet.h.

  This device is usual loadable module. (Someone please check if it can
  be made more efficient.) However, what is interesting is the way it
  allows access to user stacks (i.e. dosemu's.) i.e.  its media
  interface.

  A packet arrives to dosnet from linux for our virtual internal network
  (after routing process). If it is broadcast packet, dosnet should send
  it to all dosemu's/user stacks.  If it is normal packet, it should
  send it only particular user stack which has same destination ethernet
  address .

  It performs this process by the following method, using SOCK_PACKET
  interface , (and not introducing new devices).:

  The dosemu opens a SOCK_PACKET interface for type 'x' with the dosnet
  device. The result of this will be an addition of entry into type
  handler table for type 'x'.  This table stores the type and
  corresponding handler function  (called when a packet of this type
  arrives.)

  Each dosemu will open the interface with unique 'x'  .

     sseennddiinngg ppaacckkeettss ffrroomm ddoosseemmuu ttoo ddoossnneett
        SOCK_PACKET  allows you to send the packet "as is".  So not a
        problem at all.

     ddoossnneett -->> ddoosseemmuu
        this is tricky. The packet is simply given by dosnet device to
        upper layers. However, the upper layer calls function to find
        out the type of the packet which is device specific (default is
        eth_type_trans().).  This routine, which returns type of given
        packet, is to be implemented in each device. So in dosnet, this
        plays a special role. If the packet is identified as type 'x',
        the upper layers (net/inet/dev.c) call the type handler for 'x'.

        Looking at destination ethernet address of a packet, we can say
        deduct that it is packet for dosemu, and its type is address.)
        Type handler function for 'x' is essentially SOCK_PACKET
        receiver function which sends packet back to dosemu.

        _N_O_T_E_: the "type" field is in destination ethernet address and
        not its usual place (which depends on frame type.) So the packet
        is left intact -- there is no wrapper function etc.  We should
        use type "x" which is unused by others; so the packet can carry
        _ANY_ protocol since the data field is left untouched.

     BBrrooaaddccaasstt ppaacckkeettss
        We use a common type "y" for dosnet broadcasts. Each dosemu
        "registers" for "y" along with usual "x" type packet using
        SOCK_PACKET. This "y" is same for all dosemu's.  (The packet is
        duplicated  if  more than one SOCK_PACKET asks for same type. )

  1177..33..55..  PPaacckkeett ddrriivveerr ccooddee

  I have add the code for handling multiple protocols.

  When a packet arrives,  it arrives on  one of the two SOCK_PACKET
  handle we need to find out which of the registered protocols  should
  be handled this code.  (Earlier code opened multiple sockets, one for
  each IPX type.  However it is not useful now because we use *any*
  type.) When a new type is registered, it is added to a Type list. When
  a new packet arrives, first we find out the frame type(and hence the
  position of type field in the packet, and then try matching it with
  registered types.  [ ----  I missed comparing class; I will add it
  later.]  Then call the helper corresponding to the handle of that
  type.

  Rob, you should help in the following:

  1. Packet driver code ...

     We should now open only two sockets: one specific to dosemu and
     other broadcast. So we have to add code to demultiplex into packet
     types... I couldn't succeed. Even broadcast packets are not getting
     to dosemu.

  2. Which virtual ethernet  addresses to use (officially)?

  3. Which  special packet type can be used?

  4. Kernel overhead .. lots of packet types getting introduced in type
     handler table... how to reduce?

  1177..33..66..  CCoonncclluussiioonn

  So at last one can open multiple DOSEMU's and access network from each
  of them ...  However, you HAVE TO set up ROUTING TABLES etc.

  Vinod G Kulkarni <vinod@cse.iitb.ernet.in>

  1177..33..66..11..  TTeellnneettttiinngg ttoo ootthheerr SSyysstteemmss

  Other systems need to have route to this "new" network. The easiest
  way to do this is to have  static route for dosnet IP network included
  in remote machine you want to connect to.  After all tests are carried
  out, one could include them permanently (i.e. in gated configurations
  etc.). However, the "new" IP address should only be internal to your
  organisation, and not allowed to route outside.  There is some rfc in
  this regard, I will let you know later.  For e.g., I am working on
  144.16.98.20. Internal network I created was 144.16.112.0. (See the
  above route command.)  To connect to another linux system 144.16.98.26
  from dosemu, I include static route by running 'route add -net
  144.16.112.0 gw 144.16.98.20' on that system. It becomes more complex
  if you need to connect to outside of 144.16.98.0.

  1177..33..66..22..  AAcccceessssiinngg NNoovveellll nneettwwaarree

  Since dosemu is now on "different device", IPX needs to be either
  bridged or routed. If it is bridged, then there is no requirement for
  any extra administration ; simply run 'ipxbridge' program supplied
  with the dosnet sources. (There are two versions of it; 0.1 copies all
  packets to from/to both interface. 0.2 is "intelligent bridge", it
  copies packet to other interface only if the destination lies on other
  interface. )

  If you instead want to use "routing" for IPX, then you need to enable
  IPX config option in the kernel.  Next, you should select a network
  number that won't clash with others. Set up static direct ipx routes
  in linux, and then in one Novell netware server which is directly
  connected (i.e. without any router inbetween.). (That is where you
  should contact Novell sysadm's ;-) The idea is, the server acts as
  route broadcaster. (I haven't actually tested this; and we are working
  on getting proper daemons etc. which will make linux act as IPX router
  proper.)

  (You could include this info along with other documentation...)

  Hope this helps,

  Vinod.

  I just realised one more thing: The ipxbridge-0.2 code assumes that
  you have 'eth0' and 'eth1' as the two interfaces. And it uses this
  fact while choosing the interface to put the packet. So it won't
  recognise when 'dsn0' is used.

  ipxbridge-0.1 will work though.

  Also, note that both these programs put the card in promiscuous mode.

  So my suggestion is to "somehow" get IPX routing done by linux!

  Vinod.

  1188..  UUssiinngg WWiinnddoowwss aanndd WWiinnssoocckk

  This is the Windows Net Howto by Frisoni Gloriano <gfrisoni@hi-net.it>
  on 15 may 1997

  This document tries to describe how to run the Windows trumpet winsock
  over the dosemu built-in packet driver, and then run all TCP/IP
  winsock-based application (netscape, eudora, mirc, free agent .....)
  in windows environment.

  This is a very long step-by-step list of operation, but you can make
  little scripts to do all very quickly ;-)

  In this example, I use the dosnet based packet driver. It is very
  powerful because you can run a "Virtual net"  between your dos-windows
  session and the linux, and run tcp/application application without a
  real (hardware) net.

  1188..11..  LLIISSTT OOFF RREEQQUUIIRREEDD SSOOFFTTWWAARREE

  +o  The WINPKT.COM virtual packet driver, version 11.2 I have found
     this little tsr in the Crynwr packet driver distribution file
     PKTD11.ZIP

  +o  The Trumpet Winsock 2.0 revision B winsock driver for windows.

  1188..22..  SSTTEEPP BBYY SSTTEEPP OOPPEERRAATTIIOONN ((LLIINNUUXX SSIIDDEE))

  +o  Enable "dosnet" based dosemu packet driver:

             cd ./src/dosext/net/net
             select_packet      (Ask  single or multi ->  m)

  +o  Make the dosnet linux module:

        cd ./src/dosext/net/v-net
        make

  +o  Make the new dosemu, with right packet driver support built-in:

             make
             make install

  +o  Now you must load the dosnet module:

             insmod ./src/dosext/net/v-net/dosnet.o

  +o  Some linux-side network setup (activate device, routing). This
     stuff depends from your environment, so I write an example setup.

     Here you configure a network interface dsn0 (the dosnet interface)
     with the ip address 144.16.112.1 and add a route to this interface.

     This is a good example to make a "virtul network" from your
     dos/windows environment and the linux environment.

             ifconfig dsn0 144.16.112.1 broadcast 144.16.112.255 netmask 255.255.255.0
             route add -net 144.16.112.0 dsn0

  1188..33..  SSTTEEPP BBYY SSTTEEPP OOPPEERRAATTIIOONN ((DDOOSS SSIIDDEE))

  I suppose you know how to run windows in dosemu. You can read the
  ``Running Windows'' document if you need more information. Windows is
  not very stable, but works.

  +o  start dosemu.

  +o  copy the winpkt.com driver and the trumpet winsock driver in some
     dos directory.

  +o  start the winpkt TSR. (dosemu assign the 0x60 interrupt vector to
     the built-in packet driver)

               winpkt 0x60

  +o  edit the trumpet winsock setup file trumpwsk.ini. Here is an
     example of how to setup this file: (I think you can use less
     parameters, if you have the time to play with this file. You can
     also setup this stuff from the winsock setup dialog-box).

               [Trumpet Winsock]
               netmask=255.255.255.0  <-- class C netmask.
               gateway=144.16.112.1   <-- address in the default gateway.
               dns=www.xxx.yyy.zzz    <-- You must use right value for the dns.
               domain=hi-net.it
               ip=144.16.112.10       <-- Windows address in the dosnet.
               vector=60              <-- packet driver interrupt vector.
               mtu=1500
               rwin=4096
               mss=1460
               rtomax=60
               ip-buffers=32
               slip-enabled=0         <--- disable slip
               slip-port=2
               slip-baudrate=57600
               slip-handshake=1
               slip-compressed=0
               dial-option=1
               online-check=0
               inactivity-timeout=5
               slip-timeout=0
               slip-redial=0
               dial-parity=0
               font=Courier,9
               registration-name=""
               registration-password=""
               use-socks=0
               socks-host=0.0.0.0
               socks-port=1080
               socks-id=
               socks-local1=0.0.0.0 0.0.0.0
               socks-local2=0.0.0.0 0.0.0.0
               socks-local3=0.0.0.0 0.0.0.0
               socks-local4=0.0.0.0 0.0.0.0
               ppp-enabled=0            <-------- disable ppp
               ppp-usepap=0
               ppp-username=""
               ppp-password=""
               win-posn=42 220 867 686 -1 -1 -4 -4 1
               trace-options=16392

               [default vars]

  +o  Now you can run windows, startup trumpet winsock and .....  enjoy
     with your windoze tcp/ip :-)

  Gloriano Frisoni.  <gfrisoni@hi-net.it>

