
                    SUNSYS Protected Mode Setup Utility
                   *************************************

    The SUNSYS Setup Utility program can be used for manual configuration of
your 32bit protected mode applications that are bound to DOS/32 Advanced DOS
Extender (the stand alone DOS/32 Advanced DOS Extenders, ie dos32a.exe files
can be configured by this program as well). The usage is:

ss myprog[.exe] [config.d32]

where ss is the name of the SUNSYS Setup Utility executable file, myprog is
the name of the file (must be bound to DOS/32 Advanced) that is to be
configured, and an optional config.d32 is the file that contains the
configuration information. When the two file names are specified on the
command line, the Setup program will not be entered, but instead it will
read configuration from the second file, ie config.d32, and apply it to
the first file, ie myprog.exe. If only one file is specified on the command
line, the SUNSYS Setup program will be entered and will show a number of
colored windows on the screen.

The System Information Window will display the information about the system.

The DOS/32 Advanced Environment String Window will show the DOS32A environment
variable which can be defined in autoexec.bat file.

The Quick Help Window will show a short help message about the selected
option.

The Main Menu Window will show seven options that can be selected by
pressing the arrow keys UP and DOWN and by pressing the ENTER key to select.

Main Menu Options:

Configure DOS/32 Advanced DPMI Kernel
-------------------------------------
- Select this option if you want to configure the DOS/32 Advanced build-in
DPMI host.

Configure DOS/32 Advanced DOS Extender
--------------------------------------
- Select this option if you want to configure the DOS/32 Advanced DOS
Extender.

Create Predefined Configuration
-------------------------------
- Select this option if you want to create a Predefined Configuration that
can be used to quick configuration of your DOS/32 Advanced programs from
the command line. The changes you have made will be saved in a file *.d32.

Restore Predefined Configuration
--------------------------------
- Select this option to restore a Predefined Configuration you created
previously.

Restore Old Values
------------------
- Discard the changes you had made and restore the old values.

Restore Default Values (F6)
---------------------------
- Restore the default DOS/32 Advanced values.

Discard Changes and Exit
------------------------
- Discard the changes you had made and exit the SUNSYS Setup.

Apply Changes and Exit
----------------------
- Save the changes to the file that is to be configured and exit the SUNSYS
Setup.


DPMI Kernel Configuration Window will show the DOS/32 Advanced build-in DPMI
Kernel options and defined values.

DPMI Kernel Configuration options:

VCPI/DPMI Detection Mode
------------------------
- Controls the order of VCPI/DPMI detection. When set to VCPI/DPMI, the DOS
Extender will search for a VCPI server first, and if it is present, initialize
and use it, even if a DPMI host is present. The advantage of doing so is that
the VCPI servers are usually faster than DPMI hosts. On the other hand, a DPMI
host may always deny the VCPI presence, and in this case the DPMI will be
detected instead.

Internal Exception Control
--------------------------
- When turned on the DOS/32 Advanced will trap down the exception and report
them to the user. When turned off, the user's program is responsible for
exception trapping. Note that when the internal exception control is turned
off, the interrupts installed by DPMI functions 0203h and 0205h will be
installed as is, that is they will not be buffered by the DOS Extender but
set directly in the IDT (Interrupt descriptor table).

VCPI Smart Pages Allocation Scheme
----------------------------------
- When this function is turned on, the DOS Extender will try to be a little
smart when allocating pagetables under VCPI. It will first get the information
about how much memory is available in the 0th VCPI pagetable that always maps
the first four megabytes of memory, including the conventional memory under
1MB limit, and then map the extended memory it allocated into the free pages
in the same 0th pagetable. This way, if you have 16MB of memory in your
computer and the three of them are used by say smartdrv.exe and other TSRs,
the DOS Extender will allocate only three additional pagetables to map the
rest of the memory, ie 13MB, into them and into the VCPI's 0th pagetable.
This will in most cases save you four kilobytes of conventional memory when
running under VCPI. Turn this function off if you are having problems with
a VCPI server or if you want your extended memory to start at 4MB under VCPI,
(when turned off, the DOS Extender will not modify the 0th page table and
will start mapping the physical memory into linear memory at 4MB, ie in the
1st pagetable).

VCPI+XMS Allocation Scheme
--------------------------
- When turned on, the DOS Extender will allocate both VCPI and XMS memory.
That is, when you have an emm386.exe installed with ram nnn option where
nnn is the number of KB to reserve for EMS's use, the DOS Extender will
allocate nnn KB of extended memory from VCPI and the rest of the memory,
if any, from XMS. Otherwise, when turned off, only VCPI memory will be
allocated by the DOS Extender.

Trap and Report Software INTs
-----------------------------
- When turned on, the DOS Extender will trap and report to the user (exit
with an error message) the software interrupts that have been issued to
emulate the hardware interrupts, IRQs. For exemple, if a program issues
a software interrupt INT 08h to emulate the hardware IRQ 0 (timer), the
DOS Extender will report run-time error 6001, unexpected interrupt 08h.
Otherwise, when this option is turned off, the DOS Extender will send
the software interrupt to the interrupt handler that was installed for
the hardware IRQ 0.

Extended Memory Blocks Check
----------------------------
- When this option is turned on, the DOS Extender will check the extended
memory blocks, allocated through DPMI functions 05xxh, that they have not
been overwritten or corrupted in some way. For exemple, a program that
allocates 4MB of memory, and fills the allocated memory area with zeroes,
has an error in it. It fills 4MB + 16 bytes area instead of only 4MB area.
This way, the extended memory block header, that is placed directly after
the allocated 4MB block will be overwritten, and the DOS Extender will not
be able to allocate the next extended memory block. This situation often
arises when a program is not correctly written and often causes the application
to crash. However, the DOS/32 Advanced will always check, (if this option is
turned on) and report a run-time error message when a program overwrites
the memory it had not allocated.

Invalid Selector Limit Check
----------------------------
- When turned on, the DOS/32 Advanced DPMI function 0008h will check if the
low 12bit are set in the limits that are greater or equial to 1MB. That is
defined in the DPMI standard and protected mode programs always should do
so when they call this function. However, some programs do not set the low
twelve bit of the limit value when calling DPMI and in this cases DOS/32
Advanced DPMI will report an error to the application. Turn this option off
for DOS/4G(W) compatibility, as it does allow the invalid limits to be passed
to the DPMI function 0008h, and the DOS/32 Advanced will automatically adjust
the limit size without reporting an error.

Selectors:
----------
- This is the number of selectors that will be allocated by the DOS Extender
in the GDT (global descriptor table). You should set this value to at least
16 selectors, as DOS/32 Advanced will use some of them when loading your
protected mode application. Note that some of the protected mode programs
and games require this value to be set to a large number, for exemple 256.

Callbacks:
----------
- This is the number of callbacks that will be allocated by the DOS Extender
and that will be available through DPMI functions 0303h and 0304h. You should
set this value to at least 6 callbacks to ensure that the DOS Extender itself
operates properly, even if you know that the protected mode program you are
running does not use any callbacks at all.

Real Mode Stacks:
-----------------
- This is the number of real mode virtual stacks that will be allocated by
the DOS Extender. Whenever a protected mode code needs to access a real
mode program (for exemple an interrupt occurs, that has to be passed down
to real mode) a virtual stack will be used. When the DOS Extender runs out
of stacks (when too many nested calls are made) a run-time error message
will be displayed on the screen.

Prot. Mode Stacks:
------------------
- This is the number of protected mode virtual stacks that will be allocated
by the DOS Extender. Whenever a real mode program needs to access a protected
mode code (for exemple a hardware interrupt occurs, and the handler callbacks
it to the protected mode) a virtual stack will be used. When the DOS Extender
runs out of stacks (when too many nested calls are made) a run-time error
message will be displayed on the screen.

VCPI PageTables:
----------------
- The number of pagetables that will be allocated by the DOS Extender under
VCPI. This value directly controls how much extended memory will be allocated
by the DOS Extender (under VCPI only). Each pagetable will map (translate
linear addresses to physical addresses) 4MB of memory. Setting this value to
four will allow the DOS Extender to map 16MB of memory, but the allocated four
pagetables will take up 16KB of conventional (DOS) memory. The default value
is 16, which allows the DOS Extender to map as much as 64MB of the extended
memory. Note that the DOS Extender will automatically check how much memory
can be allocated, and will not create unnecessary pagetables, ie if this value
is set to 16, but only 8MB is physically present in the machine, the DOS
Extender will allocate only two pagetables.

VCPI PhysTables:
----------------
- The number of the pagetables that will be used for physical memory mapping
under VCPI (DPMI functions 0800h and 0801h). One pagetable will allow mapping
of 4MB of memory. Set this value to zero if you are sure that the application
you are running does not use memory mapping functions. (The physical memory
mapping is commonly used by SVGA programmers, when the video memory can be
mapped into linerar memory to make an illusion of all the memory on the video
card appearing as a contiguous block placed somewhere in the physical memory.)

Real Mode Stack Length:
-----------------------
- The size of real mode virtual stack in paragraphs (bytes * 16).

Prot. Mode Stack Length:
------------------------
- The size of protected mode virtual stack in paragraphs (bytes * 16).

Extended Memory:
----------------
- The amount of extended memory (in bytes) that will be allocated by the
DOS Extender. This much memory (if physically present) will be made available
for you protected mode program's use.



DOS Extender Configuration Window will show the DOS/32 Advanced DOS Extender
options and defined values.

DOS Extender Configuration options:

Console Output
--------------
- When turned on the DOS Extender will show the copyright banner on startup,
and report any encountered warnings to the user. When turned off, only
fatal and run-time errors will be displayed on the screen.

Sound Generation
----------------
- When turned on, any run-time error will be accompanied by a tone from the
PC speaker, to indicate that the program has crashed. This way, even when
the machine state is corrupted so that it cannot be restored, you will be
notified of an error in the program. Note that only run-time errors,
(exceptions for exemple) will be accompanied by a tone, on fatal errors
and warnings the computer will stay quiet (as my hamster was when it died).

Restore Real Mode INTs
----------------------
- When turned on, the whole real mode interrupt table (all 256 vectors) will
be saved on DOS Extender's startup, and restored on exit. Turn this off
if your protected mode program is installing the real mode interrupts that
will be used by programs in real mode, (now why would you do such a thing).

Report Modified Real Mode INTs
------------------------------
- This option controls whether the real mode interrupt vectors are to be
reported when modified by a protected mode program when it exits to DOS.
When turned on, the interrupts that was modified will be reported to the
user. Note that many protected mode programs and games install their own
IRQ handlers, which causes DOS/32 Advanced DOS Extender to install a real
mode IRQ callbacks for those, but when the program returns to DOS it does
not restore the modified interrupts. A bright exemples of such interrupts
are INT 08h, INT 09h, and INTs 1Bh, 23h and 24h. Note that the DOS Extender
will not restore the real mode IRQs separately from the real mode interrupt
vectors, so you must turn on the Restore Real Mode INTs option if you are
installing an IRQ and are not planning to restore it, or if you are having
trouble with some games that on exit reset the computer.

Object Loading Scheme
---------------------
- This is the option that gives the user the ability to manually control how
the objects (parts of your protected mode program) will be loaded into memory.
There are four different schemes available:

#1:	Load both 16- and 32bit objects into DOS memory first, when not
	enough DOS memory, load them into extended memory.

#2:	Load 16bit objects into DOS memory, when not enough, load them
	into extended memory. The 32bit objects are loaded into extended
	memory only.

#3:	Load both 16- and 32bit objects into DOS memory, when not enough
	report error and exit.

#4:	Load both 16- and 32bit objects into extended memory, when not
	enough report error and exit (DOS/4G(W) compatible).

Note that when the objects are loaded using scheme #2, the 16bit ones will
be loaded into conventional (DOS) memory by default, and there will be no
need in copying them from extended memory to DOS memory to make it possible
for real mode DOS to get an access to them. However you have to check if the
objects are really loaded low, as if there was not enough DOS memory, they
will be loaded high anyway.
The scheme #4 is DOS/4G(W) compatible. All the objects will be loaded high,
and you will have to copy the 16bit ones into DOS memory and allocate 16bit
selectors for them manually.

Clear Screen on Exception
-------------------------
- This option controls whether the screen is to be cleared and the DOS text
mode (BIOS videomode 03h) is to be set whenever an exception is encountered
in your program. When turned off, and an exception occured when the screen
was in the BIOS-not-supported videomode (for exemple so called mode-x), you
will be most likely seeing garbage.

Install Null-Pointer Protection
-------------------------------
- When turned on, the DOS Extender will install a Null-Pointer protection,
which will write protect the first sixteen bytes at the beginning of the
memory (at absolute address 0000:00000000h). You can not imagine how many
games are trashing the real mode INT 00h when returning to DOS (seems that
it has something to do with sound/music drivers).

Allow Environment Configuration
-------------------------------
- When turned on, the environment variable, DOS32A=, will be carefully
examined by the DOS Extender and if it contains any importand information,
the DOS Extender will configure itself according to what it read. Note that
the DOS Extender will in the first place configure itself using the build-in
values that are placed in the special header inside every copy of DOS/32
Advanced DOS Extender. Only in the second place will it read the environment
and if the DOS32A= environment variable is defined, the values read from it
will override the build-in values. For exemple if one copy of DOS/32A is
configured to allocate all the extended memory that is available in the 
machine, but the DOS32A= environment variable says that only 4MB are to
be allocated, the DOS Extender will follow that order and will allocate
only 4MB of memory.

Low Buffer Size:
----------------
- This is the size of the DOS Buffer in bytes. Whenever your protected mode
program reads from or writes to disk data, that is located in extended memory,
the DOS Extender must transfer it to the DOS memory first so that the real
mode DOS will be able to access it. This is the size of the buffer that the
DOS Extender will use when moving data up and down. The larger this buffer
is, the less time it will take for data to be loaded since the DOS Extender
will not have to move around a large number of data blocks. On the other
hand, when an application needs a lot of free conventional memory, it would
be wise to set the buffer size to something smaller. Note that some of DOS
extended functions will require this buffer to be at least 4KB large. Also,
the internal to DOS/32 Advanced value is stored in paragraphs, rather than
in bytes as shown, and thus all the entered numbers will be truncated by 16,
(Buffer Size AND 0xFFF0). The maximum size of the buffer is 64KB.

