pmodew.doc

来自「开放源码的编译器open watcom 1.6.0版的源代码」· DOC 代码 · 共 1,716 行 · 第 1/5 页

  Simulates a FAR CALL to a real mode procedure. The called procedure must
return by executing a RETF instruction.

In:
  AX     = 0301h
  BH     = must be 0
  CX     = number of words to copy from the protected mode stack to the real
           mode stack
  ES:EDI = selector:offset of real mode register data structure in the
           following format:

           Offset  Length  Contents
           00h     4       EDI
           04h     4       ESI
           08h     4       EBP
           0ch     4       reserved, ignored
           10h     4       EBX
           14h     4       EDX
           18h     4       ECX
           1ch     4       EAX
           20h     2       CPU status flags
           22h     2       ES
           24h     2       DS
           26h     2       FS
           28h     2       GS
           2ah     2       IP
           2ch     2       CS
           2eh     2       SP
           30h     2       SS

Out:
  if successful:
    carry flag clear
    ES:EDI = selector offset of modified real mode register data structure

  if failed:
    carry flag set

Notes:
) The CS:IP in the real mode register data structure specifies the address of
  the real mode procedure to call.

) If the SS:SP fields in the real mode register data structure are zero, a
  real mode stack will be provided by the host. Otherwise the real mode SS:SP
  will be set to the specified values before the procedure is called.

) Values placed in the segment register positions of the data structure must
  be valid for real mode. That is, the values must be paragraph addresses, not
  protected mode selectors.

) The target real mode procedure must return with the stack in the same state
  as when it was called. This means that the real mode code may switch stacks
  while it is running, but must return on the same stack that it was called
  on and must return with a RETF and should not clear the stack of any
  parameters that were passed to it on the stack.

) When this function returns, the real mode register data structure will
  contain the values that were returned by the real mode procedure. The CS:IP
  and SS:SP values will be unmodified in the data structure.

) It is the caller's responsibility to remove any parameters that were pushed
  on the protected mode stack.

2.22 - Function 0302h - Call Real Mode Procedure With IRET Frame:
-----------------------------------------------------------------

  Simulates a FAR CALL with flags pushed on the stack to a real mode routine.
The real mode procedure must return by executing an IRET instruction or a
RETF 2.

In:
  AX     = 0302h
  BH     = must be 0
  CX     = number of words to copy from the protected mode stack to the real
           mode stack
  ES:EDI = selector:offset of real mode register data structure in the
           following format:

           Offset  Length  Contents
           00h     4       EDI
           04h     4       ESI
           08h     4       EBP
           0ch     4       reserved, ignored
           10h     4       EBX
           14h     4       EDX
           18h     4       ECX
           1ch     4       EAX
           20h     2       CPU status flags
           22h     2       ES
           24h     2       DS
           26h     2       FS
           28h     2       GS
           2ah     2       IP
           2ch     2       CS
           2eh     2       SP
           30h     2       SS

Out:
  if successful:
    carry flag clear
    ES:EDI = selector offset of modified real mode register data structure

  if failed:
    carry flag set

Notes:
) The CS:IP in the real mode register data structure specifies the address of
  the real mode procedure to call.

) If the SS:SP fields in the real mode register data structure are zero, a
  real mode stack will be provided by the host. Otherwise the real mode SS:SP
  will be set to the specified values before the procedure is called.

) The flags specified in the real mode register data structure will be put on
  the real mode procedure's IRET frame. The procedure will be called with the
  interrupt and trace flags clear.

) Values placed in the segment register positions of the data structure must
  be valid for real mode. That is, the values must be paragraph addresses, not
  protected mode selectors.

) The target real mode procedure must return with the stack in the same state
  as when it was called. This means that the real mode code may switch stacks
  while it is running, but must return on the same stack that it was called
  on and must return with an IRET or discard the flags from the stack with a
  RETF 2 and should not clear the stack of any parameters that were passed to
  it on the stack.

) When this function returns, the real mode register data structure will
  contain the values that were returned by the real mode procedure. The CS:IP
  and SS:SP values will be unmodified in the data structure.

) It is the caller's responsibility to remove any parameters that were pushed
  on the protected mode stack.

2.23 - Function 0303h - Allocate Real Mode Callback Address:
------------------------------------------------------------

  Returns a unique real mode segment:offset, known as a "real mode callback",
that will transfer control from real mode to a protected mode procedure.
Callback addresses obtained with this function can be passed by a protected
mode program to a real mode application, interrupt handler, device driver,
TSR, etc... so that the real mode program can call procedures within the
protected mode program.

In:
  AX     = 0303h
  DS:ESI = selector:offset of protected mode procedure to call
  ES:EDI = selector:offset of 32h byte buffer for real mode register data
           structure to be used when calling the callback routine.

Out:
  if successful:
    carry flag clear
    CX:DX  = segment:offset of real mode callback

  if failed:
    carry flag set

Notes:
) A descriptor may be allocated for each callback to hold the real mode SS
  descriptor. Real mode callbacks are a limited system resource. A client
  should release a callback that it is no longer using.

2.24 - Function 0304h - Free Real Mode Callback Address:
--------------------------------------------------------

  Releases a real mode callback address that was previously allocated with the
Allocate Real Mode Callback Address function (0303h).

In:
  AX     = 0304h
  CX:DX  = segment:offset of real mode callback to be freed

Out:
  if successful:
    carry flag clear

  if failed:
    carry flag set

Notes:
) Real mode callbacks are a limited system resource. A client should release
  any callback that it is no longer using.

2.25 - Function 0305h - Get State Save/Restore Addresses:
---------------------------------------------------------

  Returns the address of two procedures used to save and restore the state of
the current task's registers in the mode (protected or real) which is not
currently executing.

In:
  AX     = 0305h

Out:
  always successful:
    carry flag clear
    AX	   = size of buffer in bytes required to save state
    BX:CX  = segment:offset of real mode routine used to save/restore state
    SI:EDI = selector:offset of protected mode routine used to save/restore
	     state

Notes:
) The real mode segment:offset returned by this function should be called
  only in real mode to save/restore the state of the protected mode registers.
  The protected mode selector:offset returned by this function should be
  called only in protected mode to save/restore the state of the real mode
  registers.

) Both of the state save/restore procedures are entered by a FAR CALL with the
  following parameters:

  AL       = 0 to save state
           = 1 to restore state
  ES:(E)DI = (selector or segment):offset of state buffer

  The state buffer must be at least as large as the value returned in AX by
  INT 31h function 0305h. The state save/restore procedures do not modify any
  registers. DI must be used for the buffer offset in real mode, EDI must be
  used in protected mode.

) Some DPMI hosts and VCPI/XMS/raw will not require the state to be saved,
  indicating this by returning a buffer size of zero in AX. In such cases,
  that addresses returned by this function can still be called, although they
  will simply return without performing any useful function.

) Clients do not need to call the state save/restore procedures before using
  INT 31h function 0300h, 0301h, or 0302h. The state save/restore procedures
  are provided for clients that use the raw mode switch services only.

2.26 - Function 0306h - Get Raw Mode Switch Addresses:
------------------------------------------------------

  Returns addresses that can be called for low level mode switching.

In:
  AX     = 0306h

Out:
  always successful:
    carry flag clear
    BX:CX  = segment:offset of real to protected mode switch procedure
    SI:EDI = selector:offset of protected to real mode switch procedure

Notes:
) The real mode segment:offset returned by this function should be called
  only in real mode to switch to protected mode. The protected mode
  selector:offset returned by this function should be called only in protected
  mode to switch to real mode.

) The mode switch procedures are entered by a FAR JMP to the appropriate
  address with the following parameters:

  AX    = new DS
  CX    = new ES
  DX    = new SS
  (E)BX = new (E)SP
  SI    = new CS
  (E)DI = new (E)IP

  The processor is placed into the desired mode, and the DS, ES, SS, (E)SP,
  CS, and (E)IP registers are updated with the specific values. In other
  words, execution of the client continues in the requested mode at the
  address provided in registers SI:(E)DI. The values specified to be placed
  into the segment registers must be appropriate for the destination mode.
  That is, segment addresses for real mode, and selectors for protected mode.

  The values in EAX, EBX, ECX, EDX, ESI, and EDI after the mode switch are
  undefined. EBP will be preserved across the mode switch call so it can be
  used as a pointer. FS and GS will contain zero after the mode switch.

  If interrupts are disabled when the mode switch procedure is invoked, they
  will not be re-enabled by the host (even temporarily).

) It is up to the client to save and restore the state of the task when using
  this function to switch modes. This requires the state save/restore
  procedures whose addresses can be obtained with INT 31h function 0305h.

2.27 - Function 0400h - Get Version:
------------------------------------

  Returns the version of the DPMI Specification implemented by the DPMI host.
The client can use this information to determine what functions are available.

In:
  AX     = 0400h

Out:
  always successful:
    carry flag clear
    AH     = DPMI major version as a binary number (VCPI/XMS/raw returns 00h)
    AL     = DPMI minor version as a binary number (VCPI/XMS/raw returns 5ah)
    BX	   = flags:
	     Bits    Significance
             0       0 = host is 16bit (PMODE/W never runs under one of these)
		     1 = host is 32bit
	     1	     0 = CPU returned to V86 mode for reflected interrupts
		     1 = CPU returned to real mode for reflected interrupts
	     2	     0 = virtual memory not supported
		     1 = virtual memory supported
	     3-15    reserved
    CL	   = processor type:
	     03h = 80386
	     04h = 80486
	     05h = 80586
	     06h-ffh = reserved
    DH	   = current value of master PIC base interrupt (low 8 IRQs)
    DL	   = current value of slave PIC base interrupt (high 8 IRQs)

Notes:
) The major and minor version numbers are binary, not BCD. So a DPMI 0.9
  implementation would return AH as 0 and AL as 5ah (90).

2.28 - Function 0500h - Get Free Memory Information:
----------------------------------------------------

  Returns information about the amount of available memory. Since DPMI clients
could be running in a multitasking environment, the information returned by
this function should be considered advisory.

In:
  AX     = 0500h
  ES:EDI = selector:offset of 48 byte buffer

Out:
  if successful:
    carry flag clear
    buffer is filled with the following information:

      Offset  Length  Contents
      00h     4       Largest available free block in bytes
      04h     2ch     Other fields only supplied by DPMI

  if failed:
    carry flag set

Notes:
) Only the first field of the structure is guaranteed to contain a valid
  value. Any fields that are not supported by the host will be set to -1
  (0ffffffffh) to indicate that the information is not available.

2.29 - Function 0501h - Allocate Memory Block:
----------------------------------------------