ref.gml

开放源码的编译器open watcom 1.6.0版的源代码

ES:[E]DI = Information dump buffer address, 104
bytes.        If ES is zero, no information dump is performed.
.note Outputs:
None
.note Errors:
None
.note Notes:
The user termination routine is responsible for
returning to the CauseWay termination routines to allow proper shutdown
of the application.  The instruction must be the proper 16- or 32-bit
return to match the CL register setting.  For ease of use with
high-level languages (specifically Watcom C and setting SS back to
DGROUP), [E]SI equals the internal DOS extender stack ESP immediately
prior to the 32- or 16-bit call to the termination routine.  If an
information dump buffer address is provided, register and other
termination values are placed into it using the following format:
.millust begin
dword            EBP;
dword            EDI;
dword            ESI;
dword            EDX;
dword            ECX;
dword            EBX;
dword            EAX;
word             GS;
word             FS;
word             ES;
word             DS;
dword            EIP;
word             CS;
word             reserved1;
dword            EFLAGS;
dword            ESP;
word             SS;
word             reserved2;
word             TR;
dword            CR0;
dword            CR1;
dword            CR2;
dword            CR3;
dword            csAddress;
dword            dsAddress;
dword            esAddress;
dword            fsAddress;
dword            gsAddress;
dword            ssAddress;
word             ExceptionNumber;
dword            ErrorCode;
.millust end
.endnote
.*
.section API Notes
.*
.np
A fixed segment selector at 40h is always available to the application.
This selector maps the real mode memory at 400h where most of the BIOS
variables can be found.  CauseWay also provides selectors at standard
video addresses 0B000h, 0B800h and 0A000h in non-DPMI environments to
ease conversion of real mode code.
.np
The environment variable block address in the Program Segment Prefix
(PSP) is a valid protected mode selector.  A valid protected mode
selector:offset is also placed in the PSP at offset 34h for the file
handle list pointer. Note that the default value in the program's PSP
will point to the real mode PSP, not the protected mode PSP, even if the
handle count is less than or equal to twenty. Code that makes use of the
handle list should use the address at PSP+34h rather than assuming the
list's position within the PSP.  Also, when an application is operating
non-DPMI conditions the handle table will have an entry for CauseWay's
VMM swap file.
.np
DOS functions which use the obsolete file control blocks (FCBs) are not
supported by CauseWay, although such support may be added by the developer.
.np
CauseWay applications should terminate using INT 21H function 4Ch. As
with real mode operation, the error level passed to this function in the
AL register is returned to the parent program or DOS.
.np
If a CauseWay application needs to terminate and stay resident (TSR),
then INT 21H function 31h may be used.  Unlike real mode operation, no
memory value is required for this function.  All memory owned by the
application when the TSR function is issued remains the program's
property.   There is currently no way of removing the CauseWay
application from memory once it becomes a TSR without rebooting the
machine or using a third party TSR manager.  However, a TSR manager will
not automatically release extended memory allocated for the CauseWay TSR.
.np
Unhandled exceptions terminate the program with a register display dump
to screen and a text file called CW.ERR.  CW.ERR contains other
potentially useful information about the state of the application when
it terminated.  Refer to the appendices for more information on the
CW.ERR file information format.
.np
CauseWay runs applications at privilege level 3.  Privilege level 0
reserved instructions will cause a general protection fault (GPF).
CauseWay emulates the four instructions MOV EAX,CR0; MOV CR0,EAX; MOV
EAX,CR3; and MOV CR3,EAX in the GPF handler so that they may be used by
an application.
.np
CauseWay will match a DPMI 0A00h function call with target string
RATIONAL/4G.  This in conjunction with CR0 emulation allows support of
floating point emulation by an exception handler.  Watcom uses this
approach under DOS/4GW operation if the floating point emulation library
is not linked in.  Note that this routine does not work for either
CauseWay or DOS/4GW under a DPMI host such as Windows or OS/2.
.*
.chap Interrupt Services
.*
.section Extended or Altered Interrupt Services
.*
.np
The size of registers used by CauseWay's extended or modified interrupt
services depends on the limit of the selector. Extended 32-bit registers
are used for 32-bit sized selectors and 16-bit registers are used for
selectors within 16-bits.  To reflect this, the convention of an [E] in
brackets is used before a listed register when it must be a 32-bit value
with a 32-bit selector and a 16-bit value with a 16-bit selector.
.np
Required registers that are not specified in this list should be set up
in the same way as required for normal DOS real mode operation. For INT
APIs that are not listed and require segemnt pointers, either handle
them using the CauseWay IntXX function or create your own interrupt
translation code.
.np
INT 10h
.np
10h sub function 02h, [E]DX instead of DX.
.br
10h sub function 09h, [E]DX instead of DX.
.br
10h sub function 12h, [E]DX instead of DX.
.br
10h sub function 17h, [E]DX instead of DX.
.br
13h [E]BP instead of BP.
.br
1Ch sub function 01h, [E]BX instead of BX.
.br
1Ch sub function 02h, [E]BX instead of BX.
.np
INT 21h
.np
09h [E]DX instead of DX
.br
0Ah [E]DX instead of DX
.br
0FH - 17H not supported; use corresponding file handle function.
.br
1Ah [E]DX instead of DX
.br
21h - 24h not supported; use corresponding file handle function.
.br
25h [E]DX instead of DX. Protected mode vector will be set.
.br
26h - 29h not supported; use corresponding file handle function.
.br
2Fh [E]BX instead of BX
.br
31h No value is required in DX
.br
35h [E]DX instead of BX. Protected mode vector will be returned.
.br
39h [E]DX instead of DX
.br
3Ah [E]DX instead of DX
.br
3Bh [E]DX instead of DX
.br
3Ch [E]DX instead of DX
.br
3Dh [E]DX instead of DX
.br
3Fh [E]DX instead of DX
.br
40h [E]DX instead of DX
.br
41h [E]DX instead of DX
.br
43h [E]DX instead of DX
.br
44h subfunction 02h, use [E]DX instead
.br
44h subfunction 03h, use [E]DX instead
.br
44h subfunction 04h, use [E]DX instead
.br
44h subfunction 05h, use [E]DX instead
.br
47h [E]SI instead of SI
.br
48h Protected mode memory will be allocated
.br
49h Protected mode memory will be released
.br
4Ah Protected mode memory will be resized
.br
4Bh [E]DX & [E]BX instead of DX & BX
.br
    Parameter block offset entries are [d]word
.br
4Eh [E]DX instead of DX
.br
56h [E]DX & [E]DI instead of DX & DI
.br
5Ah [E]DX instead of DX
.br
5Bh [E]DX instead of DX
.br
62h Protected mode selector will be returned
.br
6Ch [E]SI instead of SI
.np
INT 23h   Control-C Handler Address
.np
This interrupt is always reflected back to the protected mode handler to
ensure the CauseWay application can handle it correctly. The default
handler aborts the application in the same manner as DOS. If you need to
terminate your application in your own handler, perform an INT 21h
AH=4ch as normal.
.np
INT 24h   Critical Error Handler Address
.np
This interrupt is always reflected back to the protected mode handler to
ensure the CauseWay application can handle it correctly. The default
handler behaves in the same way as the DOS handler and it aborts your
application, if appropriate. If you install your own handler, all memory
accessed by this interrupt as code or data must be locker.
.np
The register values normally placed on the stack by DOS before entry to
the interrupt handler are not present in protected mode. Only the
register values are valid. You may terminate your application from
within this interrupt with INT 21h, AH=4ch as normal.
.np
INT 33h
.np
09h [E]DX instead of DX
.br
0Ch [E]DX instead of DX
.br
16h [E]DX instead of DX
.br
17h [E]DX instead of DX
.np
Notes:
.np
With the exception of software interrupts that require segment pointers
as parameters, all interrupts can be issued as normal. The most common
interrupt APIs that require segment pointers are intercepted by CauseWay
to provide normal access to these services. Any other real mode
interrupt services that require segment pointers can be accessed using
CauseWay's simulated real mode interrupt/far call services.
.np
Hardware interrupts are always reflected to protected mode handlers even
when signaled during real mode operations. This ensures that protected
mode applications always retain control without requiring you to patch
real mode interrupt vectors. The remaining interrupts are serviced via
the vector table appropriate to the mode. Use the real to protected mode
call-back services to provide real mode code with access to protected
mode code, and allow any interrupt to be re-signaled in protected mode.
.np
If you add your own hardware interrupt handlers, suchas the timer tick
at vector 08h, any memory that the handler reads or writes, including
its code, must reside in locked memory. (CauseWay provides a locked
stack.) This limitation is required because DOS is not re-entrant and
hardware interrupts can occur at any time. Interrupts occurring during
DOS activity prevent CauseWay's virtual memory manager from accessing
its swap file. Lock memory will not move to the swap file.
.*
.chap Troubleshooting
.*
.section First Steps
.*
.np
If you have problems using CauseWay, first try linking and running a
one-line program that simply prints "Hello" on your computer screen.
This will help establish if the problem is a basic incompatibility with
CauseWay and your system setup, or if the error may lie elsewhere (e.g.
a third party library).
.np
The remainder of this chapter provides a description of error and
warning messages that you may encounter when using CauseWay.  Suggested
solutions to correct the errors are included where possible.
.*
.section DOS Extender Error Messages and Return Values
.*
.np
DOS extender error messages are displayed by the CauseWay DOS extender
when a CauseWay application is running and encounters a serious problem
that it cannot recover from.  The DOS extender then terminates the
application with the appropriate return code, displaying a dump of
register values, and writing system information to the file CW.ERR.
.np
.begnote
.errnote 01 Unable to resize program memory block.
.np
Generated if DOS reports an error when CauseWay tries to resize
its real mode memory block.  As the block is always shrunk, the only
possible cause of this is corrupted memory control blocks (MCBs).
Reboot the system to correct this error.
.np
.errnote 02 386 or better required.
.np
Generated if CauseWay is run on any machine with a processor
below a 386SX.  To correct this error, run the application on another
machine or upgrade the machine's processor.
.np
.errnote 03 Non-standard protected mode program already active.
.np
Generated if the system is already operating under the control
of another protected mode program which doesn't conform to either VCPI
or DPMI standards.  Identify and remove the other application before
running the CauseWay application.
.np
.errnote 04 DOS 3.1 or better required.
.np
Generated if DOS version is less than 3.1.  You need to upgrade
the machine's DOS version or use another machine to operate the CauseWay
application.
.np
.errnote 05 Not enough memory for CauseWay.
.np
Generated if the system doesn't have enough free physical
memory to initialize the CauseWay kernel code and data. Free additional
memory before running the CauseWay application.  The memory can be any
of the extended or conventional types supported by CauseWay.
.np
.errnote 06 VCPI failed to switch into protected mode.
.np
Generated if a VCPI server is detected and the server fails to
switch into protected mode when requested.  The only likely cause of
this error is a corrupted system.  Reboot the system and try again.
.np
.errnote 07 Unable to control A20.
.np
Generated if CauseWay detects an A20 line that doesn't respond
to the normal control methods.  This may indicate either a hardware
fault or a nonstandard system.  There is no software solution for these
hardware problems.  Installing an XMS driver such as HIMEM.SYS should
address nonstandard systems.
.np
.errnote 08 Selector allocation error.
.np
Generated if DPMI refuses to allocate enough selectors for
CauseWay to function.  Remove one or more programs that are also using DPMI.
.np
.errnote 09 Unrecoverable exception. Program terminated.
.np
This is the standard General Protection Fault, or GPF,
message.  It is generated if a nonrecoverable exception occurs which
suggests a bug in the application.  Use the register dump displayed with
this message along with the information in CW.ERR and the program's .MAP
file to help track down the location and cause of the problem.
.np
.errnote 10 Unable to find application to load.
.np
Generated if CauseWay is unable to find the application within
the executable .EXE file.  This situation indicates a corrupted file.
Rebuild or obtain another copy of the application.
.np
.errnote 11 DOS reported error while accessing application.
.np
Generated if any kind of error is detected while accessing the
CauseWay application executable file.  This situation indicates a
corrupted or missing file.  Rebuild or obtain another copy of the
application.
.np
.errnote 12 Not enough memory to load application.
.np
Generated if CauseWay is unable to provide enough memory to
load the application.  Free additional memory and/or disk space before
running the application.  Check for CAUSEWAY=SWAP, TEMP and TMP
environment variables that point to a disk with little free space.  If
running under an operating system that provides DPMI per application,
increase the application's DPMI allocation.
.np
.errnote 13 DPMI failed to switch to protected mode.
.np
Generated if the machine is using a DPMI server and it fails to
switch to protected mode.  If the DPMI server only supports multiple
clients of the same type (either 16- or 32-bit) then the problem is
probably that different types of applications are already being run.
Remove the other type of DPMI application(s) before running the CauseWay
application.
.np
.errnote 14 Memory structures destroyed. Program terminated.
.np
Generated if internal memory management structures become
corrupted.  This is caused by the CauseWay application writing to memory
regions that have not been allocated to it and is a bug in the
application.  Obtain a corrected version of the application to fix this
error.
.np
.errnote 15 DOS reported an error while accessing swap file. Program terminated.
.np
Generated if any level of error is detected while accessing the
swap file.  The swap file has probably been deleted inadvertently by the
application or perhaps marked as read-only.
.np
.errnote 16 Unsupported DOS function call. Program terminated.
.np
The CauseWay application attempted to use an obsolete DOS
function which used file control blocks (FCBs).  Use the file handle DOS
functions in the application instead.
.endnote