ref.gml

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

.*
.* Macros for API heading boxes, api:eapi for API name, dsc:edsc for 
.* description.
.*
.dm @api begin
:HP2.&*.
.dm @api end
.gt api add @api cont
.*
.dm @eapi begin
:eHP2.&*
.dm @eapi end
.gt eapi add @eapi cont
.*
.*
.dm @dsc begin
:HP0.&*.
.dm @dsc end
.gt dsc add @dsc cont
.*
.dm @edsc begin
:eHP0.&*
.dm @edsc end
.gt edsc add @edsc cont
.*
.*
.*
.* Error message macros.
.*
.dm errnote begin
.se *ttl$=&'substr(&*,&'pos(' ',&*)+1)
.se *pos=0
.if &e'&dohelp. eq 0 .do begin
.   .note Error &*1
.   .bd &*ttl$
.   .ix 'Error' '&*1'
.do end
.el .do begin
:ZH2.&*
.   .cntents &*
.   .pu 1 .ixsect &*
:ZI1.&*ttl$
.   .pu 1 .ixline `&*ttl$`
.   .se *ctxn=&'substr(&*,2,&'pos(' ',&*)-2)
.   .se *pos=&'pos(',',&*1)
.   .if &*pos. ne 0 .do begin
.   .   .se *ctxn=&'substr(&*,2,&*pos.-2)
.   .   .se *ttl$=&'substr(&*,&*pos.+1)
:ZI1.&*ttl$
.   .   .pu 1 .ixline `&*ttl$`
.   .do end
.   .if '&dotarget' eq 'os2' .do begin
.   .   .if &'length(&*ctxn.) eq 3 .do begin
.   .   .   .se *ctxn='20&*ctxn.'
.   .   .do end
.   .   .el .do begin
.   .   .   .se *ctxn='2&*ctxn.'
.   .   .do end
.   .do end
.   .ctxstr &*
.   .pu 2 #define HLP_&'upper(&ctx_str.) &*ctxn
.*  .np
.*  .us &*
.do end
.dm errnote end
.*
.*
.*
.chap CauseWay Services
.*
.np
The following information describes the services available through
CauseWay for low-level protected mode compatible functions and interrupt
servicing.
.np
The CauseWay services support both 16- and 32-bit selectors. Use of
32-bit selectors allows developers to directly access many megabytes of
memory in a CauseWay program using only one selector value.  In addition
to the normal segment registers used in real mode programs, the
additional segment registers FS and GS are always available for use by
developers to access memory.  Refer to a 386, 486, Pentium or compatible
CPU reference book or manual for more information on 386+ level registers and
instructions.
.*
.section Internal Operation
.*
.np
A valid protected mode selector:offset is 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 in non-DPMI conditions the handle table will
have an entry for CauseWay's VMM swap file.
.np
The GetMem and GetMem32 calls with CX:DX and ECX set to -1 will report
the largest free memory block, rather than total free memory.  This
value may be substantially lower than total free memory due to
fragmentation of the linear memory blocks.  Set CX to -1 (0FFFFH) and DX
to -2 (0FFFEH) or ECX to -2 (0FFFFFFFEH) for GetMem and GetMem32,
respectively, for the total free memory value.
.*
.section Functions
.*
.np
.ix 'DPMI'
The CauseWay functions are based on the DPMI specification and offer
additional enhancements. This means that several of the DPMI 1.0
functions are available to the CauseWay programmer in all systems
providing access to lower level functions should you need them. All DPMI
0.9 functions are always available.
.*
.section CauseWay API
.*
.np
CauseWay provides an API for C and assembly language programmers as an
extension of the DPMI API via INT 31h.  Including the file CW.INC allows
easy access to this API through appropriately named functions.  You may
also call the CauseWay API directly with appropriate register setup.
.np
.ix 'DPMI host'
CauseWay also provides all of the DPMI 0.9 API services on systems
without a true DPMI server (thus CauseWay itself is the DPMI host in
such situations).
.np
.ix 'register list'
Some of the API services require pointers to a real mode register list.
The format of this list follows:
.millust begin
dword     EDI
dword     ESI
dword     EBP
dword     Reserved
dword     EBX
dword     EDX
dword     ECX
dword     EAX
word      Flags
word      ES
word      DS
word      FS
word      GS
word      IP
word      CS
word      SP
word      SS
.millust end
The values are passed to the target routine without any interpretation
of their contents.  There is no need to set the high words of the
extended register entries unless the target routine requires them.
.*
.section Stack Frames
.*
.np
Stack frames for 16-bit interrupts are the same as for real mode.
.np
The stack frame for 16-bit exceptions follows:
.millust begin
word SS
word SP       - Original stack address
word Flags
word CS
word IP       - Original Flags:CS:IP values
word Err Code - Processor supplied exception error code
word CS
word IP       - Return address, returns to
                interrupt/exception dispatch code
.millust end
.*
.section Defaut API
.*
.np
.ix 'CauseWay API'
The default CauseWay API follows.  Functions that include the text
.mono near
are intended only for backwards compatibility with CauseWay's near
memory model.  This model is now obsolete.  The assembly language
include file *CW.INC* also contains this list.
.*
.mbox begin
:api.AliasSel:eapi. :dsc.Create a read/write data selector from source selector.:edsc.
.mbox end
.begnote
.note Inputs:
AX= 0ff06h
.br
BX= Source selector
.note Outputs:
Carry set on error, else
.br
AX= New data selector
.note Errors:
If an invalid selector is passed in BX, this function
returns with carry set.
.note Notes:
This function always creates a read/write data
selector regardless of the source selector type.  It can be used to
provide write access to variables in a code segment.
.endnote
.*
.mbox begin
:api.CodeSel:eapi. :dsc.Make a selector execute/read type.:edsc.
.mbox end
.begnote
.note Inputs:
AX= 0ff05h
.br
BX= Selector
.br
CL= Default operation size. (0=16-bit,1=32-bit)
.note Outputs:
Carry set on error.
.note Errors:
If an invalid selector is passed in BX, this function
returns with carry set.
.note Notes:
This functions allows a selector to be converted to a
type suitable for execution.
.endnote
.*
.mbox begin
:api.CWErrName:eapi. :dsc.Change error file name, with optional drive/pathspec.:edsc.
.mbox end
.begnote
.note Inputs:
AX = 0ff32h
.br
CX:[E]DX = selector:offset of ASCIIZ error file name
.note Outputs:
None
.note Errors:
None
.note Notes:
If the error file name is invalid when a fault occurs,
CauseWay defaults to using the standard CW.ERR file name in the current
directory.  The file name including any path and drive must not exceed
80 characters or it will be truncated.  CX:EDX are not checked for
validity and passing invalid values may cause a fault within the DOS
extender.  The ASCIIZ name pointed to by CX:EDX is copied to an internal
DOS extender location and may be safely modified after calling the
CWErrName function.
.endnote
.*
.mbox begin
:api.FarCallReal:eapi. :dsc.Simulate real mode far call.:edsc.
.mbox end
.begnote
.note Inputs:
AX= 0ff02h
.br
ES:[E]DI= Real mode register list.
.note Outputs:
Register list updated.
.note Errors:
None.
.note Notes:
This function works much the same as IntXX but
provides a 16 bit FAR stack frame and the CS:IP values are used to pass
control to the real mode code.
.endnote
.*
.mbox begin
:api.GetCallBack:eapi. :dsc.Allocate real mode call back address.:edsc.
.mbox end
.begnote
.note Inputs:
AX= 0303h
.br
DS:[E]SI= Call address.
.br
ES:[E]DI= Real mode register structure.
.note Outputs:
Carry set on error, else
.br
CX:DX= Real mode address to trigger mode switch.
.note Errors:
Call-backs are a limited resource. Normally only 16
are available per virtual machine.  Use them carefully and release them
as soon as they are no longer required.
.note Call-Back:
Interrupts disabled.
.br
DS:[E]SI = Selector:Offset of real mode SS:SP.
.br
ES:[E]DI = Selector:Offset of real mode call structure.
.br
SS:[E]SP = Locked protected mode stack.
.br
All other registers undefined.
.br
To return from call-back procedure, execute an
IRET to return.
.br
ES:[E]DI =  Selector:Offset of real mode call
structure to restore.
.note Notes:
Real mode call-backs provide a means of switching from
real mode to protected mode. This function returns a unique real mode
address that when given control in real mode, switches to protected mode
and passes control to the protected mode routine supplied at entry to
this function.  On entry to the protected mode code the real mode
register structure contains all the real mode register values.
.endnote
.*
.mbox begin
:api.GetDOSTrans:eapi. :dsc.Get current address and size of the buffer used for DOS memory transfers.:edsc.
.mbox end
.begnote
.note Inputs:
AX = 0ff25h
.note Outputs:
BX = Real mode segment of buffer.
.br
DX = Protected mode selector for buffer.
.br
ECX = Buffer size
.note Errors:
None
.note Notes:
This buffer is used by the INT API translation
services, e.g., INT 21h, AH=40h (write to file). The default buffer is
8K and uses memory that would otherwise be wasted. This default is
sufficient for most file I/O but if you are writing a program that
reads/writes large amounts of data you should consider allocating your
own larger buffer and pass the buffer's address to CauseWay to speed
file I/O.
.endnote
.*
.mbox begin
:api.GetEVect:eapi. :dsc.Get Protected mode exception handler address.:edsc.
.mbox end
.begnote
.note Inputs:
AX= 0202h
.br
BL= Exception vector number.
.note Outputs:
Carry set on error, else
.br
CX:[E]DX= selector:offset of handler.
.note Errors:
The number in BL must be in the range 0-1Fh.  Anything
outside this range returns carry set.
.endnote
.*
.mbox begin
:api.GetMCBSize:eapi. :dsc.Get current memory control block (MCB) memory allocation block size.:edsc.
.mbox end
.begnote
.note Inputs:
AX = 0ff27h
.note Outputs:
ECX = Current threshold
.note Errors:
None
.note Notes:
See SetMCBMax
.endnote
.*
.mbox begin
:api.GetMem:eapi. :dsc.Allocate a block of memory.:edsc.
.mbox end
.begnote
.note Inputs:
AX= 0ff0bh
.br
CX:DX= Size of block required in bytes. (use
-1:-1 to get maximum memory size)
.note Outputs:
Carry set on error, else
.br
BX= Selector to access the block with or if CX:DX
was -1,
.br CX:DX= size of largest block available.
.note Errors:
The amount of memory available is limited by physical
memory present and free disk space of the drive being used by the VMM.
If CauseWay is unable to find a large enough block this function returns
carry set.
.note Notes:
This function allocates a block of extended
(application) memory and allocates a selector with a suitable base and
limit.
.endnote
.*
.mbox begin
:api.GetMem32:eapi. :dsc.Allocate a block of memory.:edsc.
.mbox end
.begnote
.note Inputs:
AX= 0ff0ch
.br
ECX= Size of block required in bytes. (-1 to get
maximum memory size)
.note Outputs:
Carry set on error, else
.br
BX= Selector to access the block with or if ECX was -1,
.br
ECX= size of largest block available.
.note Errors:
See GetMem
.note Notes:
This function allocates a block of extended
(application) memory and allocates a selector with a suitable base and
limit.