
 1. About Jemm386
 
 Jemm386 is an "Expanded Memory Manager", based on the source of FreeDOS
 Emm386. It should work with FreeDOS, MS-DOS and EDR-DOS. Like other EMMs
 it may provide the following services to DOS applications:
 
 - expanded memory (EMS) according to EMS v3.2 and EMS v4.0.
 - upper memory blocks (UMB) where drivers and resident programs may
   be loaded, thus increasing available free DOS memory.
 - mapping RAM to the video address segments A000-AFFF and B000-B7FF.
 - VCPI services to allow DOS applications running in V86 mode to
   switch to protected mode. VCPI also implements a simple memory management.
 - VDS API to give drivers/applications some control over DMA and physical
   addresses in V86-mode.


 2. Jemm386's Features

 The main purpose of making Jemm386 was to make it use less resources than
 other EMMs, without making compromises regarding speed or compatibility.
 The results currently are:
 
 - Jemm386 needs just 128 bytes DOS upper memory
 - Jemm386's extended memory usage is:
   + 40 kB for Jemm386 itself
   + 64 kB for the DMA buffer (default size)
   + xx kB for UMBs mapped in the first MB (always rounded up to 16 kB)
   +  4 kB fixed amount for EMS/VCPI memory management.
   + xx kB variable amount for EMS/VCPI memory management. For each 1.5 MB
        VCPI memory 64 bytes are needed, for each EMS page 5 bytes are needed.
        For the default values (120 MB VCPI, 2048 EMS pages) this is 16 kB.
 - VCPI shared address space in extended memory is just 4 kB.  

 Other features are:
 
 - Jemm386 can be loaded and unloaded from the command line. UMBs cannot
   be supplied then, however.
 - CPUs which provide the Virtual-8086 Mode Extensions (Pentium+) are
   actively supported, which increases the emulation speed.
 - Exceptions in protected-mode are detected and displayed.
 - VDS API is fully implemented.
 

 3. Commandline Options

 For a full list of available options enter:
 
 JEMM386 -?
 
 For users who previously used FD Emm386, the following options
 have been added or modified compared to FD Emm386:

 Option     Comment
 ----------------------------------------------------------
 A20/NOA20  will set the A20 enable/disable emulation accordingly.
 ALTBOOT    will install a keyboard hook, which avoids remapping of page
            0xFF000 and thus saves 4 kB, but is not 100% safe.
 D=nnn      option added to set the size of the DMA buffer to <nnn> kB.
            Max size is 128 kB. Will always be rounded to next 4 kB.
 EMM=nnn    option has been discarded. It is replaced by options NODYN and
            MIN=.
 EMX        option to prevent EMX DOS extender from quickly terminating with
            message "out of memory (RM)" on machines with large amounts
            of RAM (> 256 MB). This is optionally because it makes Jemm386
            behave not fully VCPI compliant, but shouldn't hurt usually.
 FRAME=nnn  instruct Jemm386 to use a certain page frame. Accepted are frame
            values from 8000 to E000. Usually it's better to let Jemm386 
            find a free address range to use as frame, because choosing an
            invalid frame address might cause a crash.
 I=TEST     this option is a bit less restrictive than FD Emm386 and will
            regard any 4 kB page containing identical byte values as "unused".
            FD Emm386 will only reuse a page in ROM if it is filled with
            0x00 or 0xFF byte values.
 LOAD       installs Jemm386 from the command line. Be aware that UMBs
            cannot be provided this way, since DOS will ignore them.
 [MAX=]nnn  the MAX= prefix is optional (a number found as option will
            be handled as if it has a MAX= prefix).
 MEMCHECK   option has been discarded since memory access is allowed to
            the full address space (option NOCHECK still will cause an
            exception if access is tried beyond physical RAM limits).
 MIN=nnn    preallocates <nnn> kB of XMS memory thus making sure this
            memory is truly available for EMS/VCPI.
 NOALTBOOT  option has been deleted.
 NODYN      disables XMS dynamic memory allocation.
 NOHI       this option will prevent Jemm386 from moving its resident part
            into upper memory. If no UMBs are installed by Jemm386, NOHI
            has no effect.
 NOINVLPG   disables usage of INVLPG opcode on 80486+ cpus. Some
            virtualization/emulation software (Virtual PC?) requires this 
            option to be set. There is no reason to set it when running in
            a non-virtual environment.
 NOVCPI     disables VCPI. It no longer requires option NOEMS to be set.
            This option can be set from the command line. It may be used to
            setup an environment similiar to Windows DOS boxes:
             - install Jemm386 with VCPI enabled
             - install a DPMI host residently (HDPMI, DPMIONE, ...)
             - disable VCPI with the NOVCPI option
            This forces any DOS extended application to either use DPMI
            or abort.
 PGE/NOPGE  options will enable/disable the Page Global Enable feature
            on Pentium Pro+ cpus. This allows to mark all PTEs for the
            real-mode address space 0-110000h as "global", which gives
            a slight speed benefit for VCPI applications. Option is off by
            default because some DOS extenders will not work with PGE
            enabled. Also setting both PGE + NOINVLPG will not work.
 RAM/NORAM  will instruct Jemm386 to supply UMBs or not. RAM is the default.
            NORAM is intended to be used when loading Jemm386 from the
            cmdline, in which case adding UMBs might be less useful.
 S=XXXX     has been added to add memory in address range C800-EFFF - which 
            has been activated by UMBPCI - as UMBs managed by Jemm386. For
            this to work as expected UMBPCI must be loaded *before* Himem.
            Then the Shadow RAM can be used without any additional overhead.
            NOTE: instead of using S=XXXX one might as well try tool UMBM.EXE,
            which may additionally allow to load the XMS host "high".
 UNLOAD     uninstalls Jemm386 from the command line. Uninstalling the EMM
            might confuse resident programs which rely on EMS or VCPI but
            didn't ensure this configuration to keep unchanged (by allocating
            an EMS page) while they are running.
 VCPI       (re)enables VCPI. Can be set from the command line.
 VME/NOVME  options will enable/disable using the V86 Mode Extensions
            on Pentium+ CPUs. The JEMM ;-) DOS Extender (used for "Strike
            Commander" and "Privateer") requires NOVME! These options can
            be set from the command line.


 4. EMS Implementation
 
 The following EMS 4.0 functions aren't implemented:
 
 Int 67h, AH=5Bh, alternate map register set
 Int 67h, AH=5Ch, prepare expanded memory manager hardware for warm boot
 Int 67h, AH=5Dh, enable/disable OS/E
 
 Calling these functions will return error code 84h in register AH.
 
 
 5. UMBM.EXE

 UMBM is a small tool only useful in conjunction with Uwe Sieber's UMBPCI.
 The purpose is to be able to load the XMS host into upper memory. This
 driver must be loaded before Jemm386 and therefore cannot use UMBs provided
 by Jemm386. For Jemm386 itself UMBM is not needed, because Jemm386 usually
 will move its resident part to the first UMB (unless option NOHI is given).

 How does UMBM work? It expects to find a "shadow" RAM region activated by
 UMBPCI. Then it installs inself as a temporary XMS host which just provides
 support for allocating UMBs. This is enough for most DOSes to grab the
 memory. After the UMBs have been allocated, UMBM will be removed from
 memory automatically.
 
 UMBs based on "shadow" RAM, as it is supplied by UMBPCI+UMBM, may have
 limitations depending on the motherboard's chipset. Very often the memory
 is inaccessible for DMA. Read the documentation coming with UMBPCI for more
 details.

 Enter "UMBM" on the command line and read the example how to add UMBM
 to CONFIG.SYS. UMBM has been tested to run with MS-DOS 6/7, FreeDOS and
 EDR-DOS.

 
 6. Troubleshooting

 If Jemm386 halts the machine or causes a reboot, the following combinations
 of parameters may help to find the reason. Generally, Jemm386 should
 be loaded immediately after the XMS host (HIMEM.SYS or HIMEM.EXE), and
 the XMS host itself should be the very first device driver to be loaded.
 For testing, it might also help to prevent DOS from loading in the HMA
 and/or to use UMBs at all.
 
 -  X=A000-FFFF NOHI NOVME

    This is the safest combination. If this doesn't work, Jemm386 most
    likely isn't compatible with the current DOS/BIOS.
    
 -  X=TEST NOHI NOVME
    
    This is slightly less safe, since Jemm386 will scan the upper memory
    region to find "unused" address ranges usable for UMBs. If this 
    doesn't work, one has to manually set X=xxxx-yyyy to finally
    find the region which causes the troubles.
 
 
 7. History

 03/02/2007: v5.45
 
 - bugfix: in v5.40, if no option was entered when installing Jemm386, it
   might have displayed some garbage.
 - bugfix: invalid opcode generated by Jemm386 if running on a cpu < 80386.
 - bugfix: XMS function 11h (free UMB) always returned an error.
 - option UNLOAD added.
 - option RAM/NORAM implemented.
 - valid range for page frame set with FRAME=xxxx now 8000-9FFF.
 - the MAX= prefix can be omitted now. Makes the cmdline more MS Emm386 
   compatible.
 - memory required for UMBs will no longer reduce the memory available for
   EMS. This is similiar to what MS Emm386 does.
 - installing Jemm386 from the command line now prohibited if a DPMI host
   is installed.
 
 02/20/2007: v5.4
 
 - some minor bugfixes.
 - Jemm386 now moves its resident part to the first UMB which it supplies.
 - NOHI option implemented.
 - Jemm386 now uses the true (=zero-based) flat memory model.
 
 01/11/2007: v5.34
 
 - bugfix: Jemm386 always hooked int 15h, ah=4Fh, thus always acting as
   if option ALTBOOT was set (bug introduced in v5.25).
 
 01/06/2007: v5.33
 
 - bugfix: Jemm386 erroneously might have disabled EMS (on EDR-DOS only?).
 - reboot code slightly changed, there were still some machines (old 80486?)
   were Ctrl-Alt-Del didn't work.
 
 11/13/2006: v5.32
 
 - removed an optimisation which PKZIP didn't like.
 
 11/09/2006: v5.31
 
 - some minor bugfixes in function int 67h, ah=57h.
 - bugfix: wrong register contents were displayed in v5.30 for exceptions
   occuring in protected-mode.
 - v86-mode int 06 handler moved to protected-mode, thus further reducing 
   Jemm386's conventional memory usage.
 
 10/27/2006: v5.30
 
 - bugfix: int 67h, ah=57h (move/exchange memory region) didn't always
   invalidate the TLB cache for the EMS memory to copy/exchange.
 - bugfix: int 67h, ax=4F01h didn't work.
 - int 67h, ah=55h/56h implemented.
 - int 67h, ah=57h now works with overlapping memory regions. Furthermore
   it is now ensured that all EMS pages involved in the copy operation are
   valid before copy actually begins.
   
 10/24/2006: v5.29

 - bugfix: the error msg when the EMS call to map UMBs failed contained
   garbage as "function".
 - int 67h, AH=58h will now return success even with NOEMS.
 - now error code 80h, not 91h is returned if functions int 67h,
   ah=41h or 47h or 48h are called and no page frame is defined.
 - NOINVLPG option added.
 - I=TEST is now a bit less restrictive and will increase compatibility
   with MS-Emm386.
 - help text displayed by Jemm386 adjusted where it was wrong or unclear.
   
 10/13/2006: v5.28

 - bugfix, VDS function scatter/gather lock (int 4Bh, ax=8105h): if lower
   12 bits of offset in EDDS were <> 000h, this function always returned 
   the first page as a separate region.
 - bugfix, VDS function scatter/gather lock: if this function failed with
   AL=9, it did not always set the correct value for items required to
   describe the full region.
 - bugfix: int 67h, ah=53h (get/set handle name) and ah=54h (get handle
   directory) wrongly assumed that they won't be called with handles other
   than 0000 if NOEMS is set.
 - bugfix: int 67h, ah=57h (move/exchange memory region) didn't work without
   a page frame (NOEMS or FRAME=NONE).
   
 10/07/2006: v5.27

 - bugfix: allocating a EMS block with zero pages (int 67h, ah=5Ah, bx=0)
   returned with AH=0, but did not return a valid handle in DX.
 - bugfix: calling int 67h, AH=51h modified AL register.
 
 09/30/2006: v5.26
 
 - bugfix: VDS functions 03, 04, 07 and 08 may have failed if bit 1 of DX
   was set (request to copy in/out of DMA buffer) and registers BX,CX 
   were <> 0.
 - bugfix: 1 kB of DMA buffer may have been inaccessible.
 - bugfix: releasing a DMA buffer with size > 0 and < 1 kB always failed.
   
 09/22/2006: v5.25
 
 - bugfix: if option ALTBOOT is set and Ctrl-Alt-Del being pressed has
   been detected, then the real-mode int 15h chain is called first before
   rebooting. This gives other hookers (SmartDrv) a chance to cleanup.
 
 09/19/2006: v5.24
 
 - bugfix: int 67h, ax=5001h (implemented in v5.2) didn't work.
 - bugfix: setting Jemm386 options from the command line did reset
   the options which were not explicitely entered.
 - PGE/NOPGE options added.
 
 09/14/2006: v5.23

 - bugfix: if the amount of preallocated EMS memory (MIN=xxxx) was
   not below largest XMS memory block - 384 kB, the amount of free/
   available EMS pages reported by Jemm386 was up to 384 kB too large.
 - implemented VDS function 05 (scatter lock) returning PTEs instead of
   "regions". This makes Jemm386 fully support the VDS API.
 - some message texts adjusted to make it clear what is an error, a
   warning or just informational.
 - warning about detected system memory region now displays all such
   regions, start and size.
 - if wanted EMS memory has to be reduced, a warning is displayed.
 - UMBM.EXE added.
 - EMX option added.
 
 09/09/2006: v5.22 
 
 - bugfix: the DMA buffer 64kb alignment may cause up to 32 kB to be lost
   for EMS/VCPI memory. This wasn't taken into account, and may have
   resulted in Jemm386 unable to alloc UMBs if options NODYN and 
   MIN=<value below size of UMBs+32> were set.
 - bugfix: in displayed text "wanted preallocated EMS memory <nnn> kB" 
   <nnn> was always blank.
 - space for UMBs now rounded up to next 16 kB boundary (previously it
   was rounded to 32 kB).
   
 09/07/2006: v5.21 
 
 - bugfix: in v5.2 if an invalid command line parameter was entered, the
   program displayed garbage.
 - bugfix: in v5.2 options setting both options NOEMS and NOVCPI might
   have caused Jemm386 to run out of memory for UMBs.
 - XMS dynamic memory allocation was automatically disabled if NOEMS and
   NOVCPI options were set, but this is no longer useful since option NODYN
   exists and VCPI can be dynamically set/reset from the command line.
 - DMA buffer size now always rounded up to a full 4 kB boundary.
 - LOAD option added which allows to install Jemm386 from the command line.
 
 09/06/2006: v5.2 

 - bugfix: writing to "ROM" page FF000 if ALTBOOT wasn't set caused a crash.
 - bugfix: if XMS handle array was in HMA and A20 got disabled results may
   have been "unexpected".
 - bugfix: "disable A20 local" emulation did not return an error code if
   count was already 0.
 - there was slightly more XMS memory allocated than required.
 - support for Int 67h, ax=5001h implemented.
 - option MIN= no longer deactivates XMS dynamic memory allocation.
   option NODYN added, option EMM= discarded.
 - If XMS memory must be preallocated (because XMS host doesn't export its
   handle table) and MIN= option is not set, Jemm386 allocates half of
   extended memory (but not more than 32 MB) for EMS/VCPI memory.
 - Assembler: MASM may be used instead of TASM.
 - Compiler: Open Watcom WCC or MS VC 1.5 may be used instead of TC.
 - Linker: Digital Mars OPTLINK may be used instead of TLINK.
 - protected-mode code switched to 32-bit.
 - port trapping added to the A20 enable/disable emulation. XMS hook is
   still required due to the "A20 always on" case, which causes most XMS
   hosts not to touch the ports at all.
   
 08/30/2006: v5.1

 - bugfix: the DMA master mask register was read, which doesn't work
   on all machines and may have caused an "illegal instruction exception"
   if the floppy disk was accessed. This bug was introduced in v5.00.
 - bugfix in EMS function 4Eh.
 - bugfix: A20 emulation works now if no UMB handler has been installed.
 - DMA buffer size may be set by commandline option. 
 - VDS functions 07/08 (request/release DMA buffer) and 09/0A (copy
   into/out of DMA buffer) implemented. VDS functions 03/04 (lock/unlock
   region) extended so that they call functions 07/08 if needed. 
 - NOVCPI does no longer require NOEMS.
 - ALTBOOT (re)implemented, it hooks int 15h, ah=4Fh now.
 - VME mode may now be set/reset with VME/NOVME options. 
 - LIBM.LIB no longer needed to create the JEMM386.EXE binary.
 
 08/25/2006: v5.01
 
 - bugfix: "A20 enabled"-count was 0 on startup, should have been 1.
 - bugfix: unsupported VDS functions caused a debug display, which didn't
   work and may have caused corruption of monitor data. Debug displays
   removed.
 - bugfix: original int 4Bh vector may have been 0000:0000 - if this is
   true, it must never be chained to of course. Instead carry flag is set.
 - VDS functions 0Bh and 0Ch (disable/enable translation) implemented.
 
 08/23/2006: v5.00
 
 - EMMXXXX0 device communication implemented
 - bugfix: DMA buffer is ensured to begin on a 64 kB physical address
   boundary.
 - bugfix: XMS handles which are no longer used now get the "in pool" flag
   set, not the "free" flag.
 - Pentium+ VME extensions supported. 
 - A20 disable emulation activated.

 08/17/2006: v5.00pre 

 - bugfix: in VCPI protected mode entry switch to host stack before
   context is switched.
 - command line option S=xxxx added.
 - option NOALTBOOT deleted.
 - the full physical memory is no longer mapped in the address space.
   This reduces extended memory usage a lot on machines with large amounts
   or RAM, since no page tables are needed.
 - VDS code moved to extended memory, reducing conventional memory usage
   by about 1 kB.

 
 8. License
 
 See file LICENSE.TXT for details.
 
 Japheth

