--------------------------------------------------------------------------------
INSTALL.TXT	    DPMI-RSX  (c) Rainer Schnitker	    9/93
--------------------------------------------------------------------------------

This file contains information about:

        Hardware Requirements
        Software Requirements
        Create more DPMI memory
        INSTALL for EMX/GCC
        INSTALL for DJGPP
        Major bugs in tested DPMI-Hosts
        Command line switches
        Debugging with RSXDEB.EXE or RSXDJDEB.EXE




    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 + QDPMI 1.01

	386MAX 6.x (better 7.0)

	(OS2, 386Unix not tested)

  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.8/e/f/g or DJGPP 1.06-1.10

  or any EMX program that should run under DPMI.




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

MS-Windows 3.1:
    You can set the value PageOverCommit in the system.ini [386Enh] section
	PageOverCommit=8     (default=4)
    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.

    Also you can create a smaller DOS-Box. PIF-settings:
	- 400 KB DOS memory maximum
	  (if you only want to run small DOS programs in RSX)
        - EMS=0 ; XMS=0 ; no High-Memory-Area


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 is 64 MB, you don't need to change it
    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

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

 a) Set the environment variable EMX to something like
	EMX = C:\RSX\BINEMX\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.

 b) If you want to run both systems, you can use the patched stub emxlboth.exe
    for emxbind. If emxlboth detects only DPMI it runs RSX.EXE, otherwise
    EMX.EXE (memory manager with both vcpi/dpmi or no dpmi-server).
    The new stub must find RSX.EXE in the current directory, in the PATH or
    in a RSX environment (like emxl.exe search for EMX environment).
    Example:
        C:> gcc -o myfile.exe myfile.c
	C:> emxbind -u \rsx\binemx\emxlboth.exe  myfile.exe
	C:> myfile	(runs RSX, if only DPMI detected)
    If you run RSX from the command-line change the PATH or copy the
    \rsx\binemx files to \emx\bin.

    There is a second stub emxldpmi.exe, which runs RSX if DPMI detected.

Notes:
    (a) Older emx versions don't use the EMX environment (emTeX386).
	Use emxbind -u to change the emxl.exe stub (or emxlboth.exe).

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

    (c) If you grow the stack (note b), some programs require -as option
	(see command line switches).





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

1)  Set environment RSX387, if 387-emulation is required.
	RSX387=C:\RSX\FPU-EMU\RSX387

2)  Bound executable must find RSXDJ.EXE in the PATH or current directory.
    Copy the files RSXdj.EXE, RSXDEBdj.EXE from the \rsx\bindj to your
    \djgpp\bin directory. Or change the PATH to \rsx\bindj.

3)  You must use the new stub STUBDJ.EXE to create bound executable. The
    program BINDEXE puts a stub and the a.out program together:

	BINDEXE stubdj.exe myfile myfile.exe

    Stubdj executes RSXdj 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 BINDEXE command to create the new stub.

    BINDEXE can used for any stub (also stub.exe from DJGPP).

    Example:
	C:\GCC\BIN> exe2aout gcc.exe		    (creates a.out-file gcc )
	C:\GCC\BIN> bindexe stubdj.exe gcc gccd.exe (copy stubdj+gcc gccd.exe)

	This example creates a different compiler-name gccd.exe to run RSXDJ
	if DPMI is detected.


X1) Change read.o in LIBC.A if DJGPP version <= 1.08.
    -> see \rsx\doc\caution.g32
    Or use the program DPMIFIX from DJGPP 1.10.

X2) Extra: Building smaller programs
    Relink .o files with LDN.EXE to create a new a.out file (or use GCCN.EXE).
    LDN creates emx-like executable. LDN and GCCN are in the \rsx\bindj\newld
    directory.

X3) Extra: Using new library LIBRSX.A (contain signals,ptrace,spawnve)
    Read the file 'readme' in the \rsx\source\djlibrsx to install
    this futures.





Major BUGS in tested Hosts :
----------------------------

    running MS-Windows 3.1
	- client can't use int3 breakpoint (poor GDB)
	  so you must use the internal debugger (uses hardware breakpoints)

    running QEMM + QDPMI 1.01
	- page faults terminate program
	- QDPMI virtuel memory error after memory resize fails (page fault)
	  (can happen in GDB.EXE)

    running 386MAX 6.00 (the new version 7.00 is ok)
	- gp-fault in host handler calling spawning() for a real-mode program
	- control-c handler will never called





COMMAND LINE SWITCHES ( a subset of EMX switches )
--------------------------------------------------

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

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

    Example:  SET RSXOPT=-s512 -e
	    This builds a 512KB stack for every programs
	    and disables rsx387 loading.


Switches:

-a[cmwi] enable some extra DOS features:
     -ac makes data,stack,heap executable (default for DJGPP)
     -am enable _memaccess() (for writing 0xA0000h-0xFFFFFh), but this
	 option destroy protection under RSX (see source code sysemx.c)
     -aw enables write access to all areas for EMX,
         RSX ignore this
     -ai enables _portaccess() for EMX,
         RSX ignore this (DPMI-Server allow/emulate this)

     -as (RSX only) Don't limit stack-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 only if the default stack is changed.
	 If the stack is changed, the place of the stack region is changed.

	 EMX prg    0		64KB
	 default:   |--<<stack---|--code--|--data/bss--|--heap--
		     ^lower limit expand-down

         DJGPP prg  0                    4MB
         default:   |-code-|------<<stack-|-code-|-data/bss-|-heap-
			    ^lower limit expand-down

	 -s option
	 big stack: |----------|-code-|-data/bss-|----------<<stack-|-heap-
                     ^no limit                   ^limit expand-down
		      (-as option)

         emTeX386 need the -as option, if you grow the stack (others not found)
         (see also -s option)

-c   disable core dumps (core dumps not implemented yet).

-e   Don't check 387 coprocessor.
     Under RSX this disables loading 387 emulation. If the cpu detect a
     floating point exception, the program will terminated with signal SIGFPE.

-s#  set stack size in KB.
     default: 64 KB for EMX
              4 MB - text_size for DJGPP
     (!) Note:
         If you grow the stack for EMX programs the stack region is placed
         in another area. If there is a stack fault using the EBP register
         set the -as option to disable stack limit.
        (see -s option)

-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

-S   Enable internal debugger (use RSXDEB.EXE)

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

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



Debugging with RSXDEB.EXE or RSXDJDEB.EXE:
------------------------------------------

To enable the builtin-debugger use the -S option.

Example for EMX:
	C:> gcc -g -o myfile.emx myfile.c
	C:> rsxdeb -S myfile.emx

Example for DJGPP:
	C:> gcc -g -o myfile.dj myfile.c
	C:> rsxdjdeb -S myfile.dj

type help or h	for help

The input line has some doskey futures.
 (home, end, insert, delete, cursor moves, esc)

