--------------------------------------------------------------------------------
INSTALL.TXT	    DPMI-RSX  (c) Rainer Schnitker		    May 1994
--------------------------------------------------------------------------------

This file contains information about:

	* Hardware Requirements
	* Software Requirements
	* Create more DPMI memory
	* INSTALL for EMX/GCC
	* INSTALL for DJGPP
	* RSX32
	* Command line switches for rsx
	* Major bugs in tested DPMI-hosts
	* Patch for next EMX-Update
	* Error messages from RSX




    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.



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



Hardware Requirements:
----------------------

- RSX requires a 386SX-CPU (or higher)

  (A 387 coprocessor is not necessary, because RSX emulates it)




Software Requirements:
----------------------

- A DPMI 0.9/1.0 - Server like:

	MS-Windows 3.1 enhanced mode

	QEMM386 7.xx / QEMM386 + QDPMI 1.01

	386MAX 6.x, 7.x

	OS/2 2.x

	MS-Windows NT

  To use the 387-emulator the DPMI-server must provide DPMI 1.0 floating-point
  extensions (most 0.9 server support this).

- DOS 3.3+ or DOS box emulation

- A GNU-C port for DOS like EMX/GCC 0.8e-h or DJGPP 1.06-1.11

  or any EMX program that should run under DPMI (like TeX386 beta11).




Create more DPMI memory:
------------------------

If your GCC programs (TeX386, EMX/GCC or DJGPP) run out of memory,
you should read this section.


MS-Windows 3.1:
    1) Increase or install a *permanent* Swapfile (Control Panel / 386).

    Without a permanent Swapfile, you can't run TeX386 from emTeX, if you
    have only 4 MB physical memory. (TeX message "DYN: out of memory").

    If you can't incease the swapfile, you can set the value PageOverCommit
    in the system.ini [386Enh] section, insert
	PageOverCommit=8
    the default value is 4. After that restart Windows.
      [ PageOverCommit=value:
      Specifies the multiplier for determining the amount of linear address
      space. The amount of linear address space is computed by rounding up the
      amount of available physical memory to the nearest 4 megabytes and then
      by multiplying that value to the value specified for this setting. ]
    After that, you should increase the permanent Swapfile again.

    2) Also you can create a smaller DOS-Box. PIF-settings:
	- 300 KB DOS memory maximum
	- EMS=0 ; XMS=0 ; no High-Memory-Area
    But this option is not so useful as point 1).


386MAX 7.0:
    To increase memory you must have a SWAPFILE line in your 386MAX.PRO file
	SWAPFILE=C:\386MAX\386MAX.swp /S=10240
    This creates a 10MB swapfile. The size of the virtual swapfile is the
    amount of virtual memory available to your applications.

QEMM + QDPMI:
    Set the environment QDPMI to something like
	QDPMI=SWAPFILE c:\tmp\qdpmi.swp 8192
    This creates a 8 MB swapfile. The sum of the value of availble memory and
    the size of the virtual swapfile is the amount of virtual memory available
    to your applications.

OS/2:
    DPMI_DOS_API must have the value AUTO or ON
    DPMI_MEMORY_LIMIT default value should 64 MB
    EMS,XMS is not needed.



INSTALL for EMX/GCC:
--------------------

1)  Set the environment RSX387, if a 387-emulation is required
	RSX387=C:\RSX\FPU-EMU\RSX387
    If you run RSX, it loads RSX387, if there is no coprocessor.
    You can disable this with the '-e' command-line switch.

    RSX32 has a buildin emulation, so you don't need RSX387.

2)  There are two ways to run RSX from bound exe-files:

 a) Use emxl.exe from EMX-0.8H.
    If the emxl.exe detects only DPMI it runs RSX.EXE, otherwise EMX.EXE.
    emxl.exe must found RSX.EXE in the current directory or in the PATH.
    Also you can use the Environment RSX=<path>\RSX.EXE (like EMX).
    See also \emx\doc\EMXRT.DOC in EMXRT.ZIP.

 b) Set the environment variable EMX to RSX.EXE like
	EMX = C:\RSX\BIN\RSX.EXE .
    Now, bound EXE-files run the RSX-extender instead of EMX. A special PATH
    statement is not necessary.

    If you have no coprocessor and you want run the gcc compiler this method
    is recommend. Also you can use the stub emxldpmi.exe. This stub runs
    always RSX, if there is a DPMI-server.


Notes:
    (a) Note that the default stack is 60 KB. If you need more space, use
	the -s option to grow the stack, or set a environment-var RSXOPT.
	Example: RSXOPT=-s256 sets the stack to 256 Kbytes.
	(see rsxcmds.txt).



INSTALL for DJGPP:
------------------

1)  Set environment RSX387, if 387-emulation is required.
	RSX387=C:\RSX\FPU-EMU\RSX387
    If you run RSX, it loads RSX387, if there is no coprocessor.
    You can disable this with the '-e' command-line switch.

    RSX32 has a buildin emulation, so you don't need RSX387.

2)  Bound executable must find RSX.EXE in the PATH or current directory.
    Copy the binary files from \rsx\bin to your \djgpp\bin directory.
    Or change the PATH to \rsx\bin.

3)  Creating bound executable:
    a) For go32 version 1.11 you can use the tools coff2exe, stubedit.
    To create a gcc compiler for RSX.EXE do this:
	C:\GCC\BIN> xcopy gcc.exe gccdpmi.exe
	C:\GCC\BIN> stubedit gccdpmi.exe extender=rsx

    b) for older versions:
    You must use the new stub STUBDJ.EXE to create bound executable. The
    program BINDDJ puts a stub and the a.out program together:

	> BINDDJ stubdj.exe myfile myfile.exe

    Stubdj executes RSX if a DPMI-server is there, and go32.exe if there is no
    DPMI-server. To change the gcc compiler exe-stub, use EXE2AOUT from djgpp
    to get the a.out file and use the BINDDJ command to create the new stub.

    Example:
	C:\GCC\BIN> exe2aout gcc.exe
	C:\GCC\BIN> binddj stubdj.exe gcc gccd.exe (copy stubdj+gcc gccd.exe)


[4] Building library LIBRSX.A
    If you want to use signals(), ptrace(), wait(), etc you must build
    the library 'librsx.a'.
    Read the file 'readme' in the \rsx\source\djlibrsx to install
    this futures.



RSX32:
------

RSX32 does the same as RSX. RSX is compiled with EMX/GCC and don't use
the EMX C-Library. RSX has a builtin FPU-EMU, rsx387 is not needed.
This is the first release, so RSX32 it beta.

You run RSX32.EXE instead RSX.EXE
Set EMX=c:\rsx\bin\rsx32.exe and RSX=c:\rsx\bin\rsx32.exe
Or rename RSX to RSX16 and RSX32 to RSX.



Command line switches for rsx ( a subset of emx switches )
----------------------------------------------------------

Syntax:
	RSX [options] a.out-file
	RSX32 [options] a.out-file

You can put command-line switches in the RSXOPT environment.

    Example:  SET RSXOPT=-9 -e0
	    This disables DPMI 1.0 services
	    and disables any coprocessor usage.


Switches:

-a[cmwi] enable some extra DOS features:
     -ac makes data and the stack executable (default now)
     -am enable _memaccess() (for writing 0xA0000h-0xFFFFFh)
	 This option destroy protection under RSX with DPMI 0.9
	 (see source sysemx.c/loadprg.c)
	 Under DPMI 1.0 the first DOS megabyte is mapped to the
	 log. address 0x3C0000L (= 60 MB)
     -aw enables write access to all areas
	 DPMI 0.9 don't allow write protection
     -ai enables _portaccess() for EMX,
	 RSX ignore this (DPMI-Server allow/emulate this)

     -as (RSX only) Don't use expand-down-stack-segment, ss = data segment.

	 RSX uses expand-down stack-segments to control the stack. But some
	 gcc-programs uses the EBP register for a pointer in the data-segment.
	 This causes a stack-fault (but not with the default stack).
	 If the stack is changed, the place of the stack region is changed.

	 RSX default:

	 0	     64KB
	 |--<<stack---|-----code-----|----data/bss----|--heap------

	  ^- lower limit expand-down  <full access esp,ebp>


	 RSX with big stack / DJGPP 1.11:

	 |-------|---code---|---data/bss---|----<<stack-------|--heap--
	      <no access esp,ebp>	   ^lower limit expand-down



	 older emTeX386 need the -as option, if you grow the stack
	 (beta11 is ok / Jan 1994)


-c   disable core dumps (ignored: core dumps are not implemented)

-e   Don't check 387 coprocessor.

     Under RSX this disables loading 387 emulation if you have no coprocessor.
     On floating point instructions, the program will terminated with signal
     SIGFPE (this is like -e2).

     With a coprocessor the status is not saved between processes.
     There are no DPMI calls for the 387 (this is like -e0).

     Now there also this switches,
     -e0 -e1 -e2 -e3
     force the fpu-status:

     Bit     Significance
     0	     new value of MPv bit for client's virtual CR0
	     0 = disable numeric coprocessor for this client
	     1 = enable numeric coprocessor for this client
     1	     new value of EMv bit for client's virtual CR0
	     0 = client will not supply coprocessor emulation
	     1 = client will supply coprocessor emulation

     This means for RSX:

     e0: don't set FPU status                       [for buggy DPMI-host]
     e1: enable FPU, don'emulate                    [if you have a 387,487,..]
     e2: disable FPU, but catch FPU instructions    [set 387 not present]
     e3: enable FPU, emulate FPU instructions	    [emulate all FPU instr]

     If your DPMI-host crash after terminating the emx-program, try -e0
     (Novell DOS 7.0  emm386)


-s#  set stack size in KB

     default:
       60 KB under DPMI 0.9 : from 4 to 64 KB (text_start)

     Under DPMI 1.0 the stack grows from 60 MB to the heap (brkv - 60 MB)
     The stack size is ignored.

-p   for EMX: don't use all low DOS memory.

     for RSX: don't put rsx387 emulator in DOS memory
	      DPMI doesn't use DOS memory for swapping

     RSX32 don't load rsx387.

-V   Display RSX version

-9   Force DPMI 0.9 services
     If you have problems with your DPMI 1.0 server use this option

-I   print all int0x21 calls (only for testing RSX)

-P   print some extra information (only for testing RSX)
     print registers after exception





Major bugs in tested hosts :
----------------------------

    MS-Windows 3.1
	- (debug handler different - but RSX can handle this)

    386MAX 7.00 (DPMI1.0 server: support demand paging with rsx)
	- ResizeLinearMemory bug (RSX don't use this)

    386MAX 6.00
	- RSX Control-C handler will never called
	- (no virtuel memory)

    QEMM + QDPMI 1.01  [ QEMM 7.xx not tested ]
	- page faults terminate program
	- QDPMI virtuel memory error after memory resize fails (page fault)
	  (happened in GDB.EXE)

    Novell DOS 7.0 EMM386
	- crash on DPMI 1.0 calls -> 387 emulation is not possible
	  you *must* use the '-e0' option

    OS/2 2.x (not tested, TeX386b11 should run)
	- Problems with memaccess()
	- DPMI int 0x31 don't switch stacks

    NT (not tested, TeX386b11 should run)
	- you must use the '-e0' or '-e' option



Patch for next EMX-Update:
--------------------------

If you upgrade a new EMX version (maybe emx0.8i ?), you always get a warning
message, if you run the rsx.exe file.

Now you can patch the RSX.EXE file:

	Take a good hexdump-editor
	Load RSX.EXE
	Search for reversed version number "h8.0"
	Change this value
	Save RSX.EXE



Error messages from RSX:
------------------------

"No DPMI-host found!"
    There is no DPMI-server. Use EMX instead.

"32bit programs not supported"
    The DPMI-server supports only 16-bit programs. You can't use RSX.

"Can't alloc memory for the DPMI-host-stack"
    The DPMI-server needs some DOS memory for RSX.
    Do you have enough DOS memory?

"can't switch to Protected Mode"
    DPMI-server can't switch RSX in Protected Mode.
    Do you have enough extended memory?

"No DPMI-server 387 support", "use -e option"
    DPMI-server doesn't support a coprocessor. Use 'RSX -e prog' or set
    the environment 'RSXOPT=-e'.

"error:can't get int21", "error:can't set int21"
    RSX can't change the interrupt vector 0x21.

"error: not a valid PSP option -/xxxx/\n"
    EMXBIND error in bound executable.

"Can't find RSX387"
    Set the environment RSX387 like RSX387=c:\rsx\fpu-emu\rsx387

"Can't load emu: "
    Not enough memory for 387 emulator. Try -p option or increase DOS
    memory.

for emTeX386 users: "DYN: out of memory"
    is a TeX message, increase your DPMI memory.
    Since TeX386 uses a big heap (3-4 MB), a permanent swapfile in Windows
    is recommend with only 4MB installed.

