xlib.doc

XLIB 2.0版 32位应用程序开发 ASM/C语言的DOS 扩展库

  CPU Mode:  Real
  Registers at Call:  None
  Return Registers:
     Sign bit of DX clear if successful.  Memory requirements in bytes are
  returned in DX:AX.
     Sign bit of DX set if unsuccessful.  An error code is returned in AX
  (always a DOS error code).
  Details:
     DX:AX is adjusted upward to an integer multiple of 16.
     If both DPMI and VCPI are present, then XLIBMEMREQ will assume that DPMI
  will be used if bit 0 of IFLAGS is clear (the default); otherwise, VCPI is
  assumed.  No additional conventional memory is needed if both DPMI and VCPI
  are absent.
     This routine will return DX:AX = 0 if XLIB contains free internal memory in
  sufficient quantity to meet conventional memory demands.
     This routine obtains DPMI requirements by calling DPMIMEMREQ (see below)
  and VCPI requirements by calling VCPIMEMREQ.





                                        7






  DPMIMEMREQ  (DPMI Memory Requirements)
  Purpose:  Find DPMI conventional memory requirements.
  CPU Mode:  Real
  Registers at Call:  None
  Return Registers:  DX:AX = conventional memory requirements.
  Details:
     DX:AX is adjusted upward to an integer multiple of 16.
     This routine does not assume the presence of DPMI.  It will return DX:AX =
  0 if DPMI is absent.
     This routine will return DX:AX = 0 if XLIB contains free internal memory in
  sufficient quantity to meet the conventional memory demands of DPMI.

  VCPIMEMREQ (VCPI Memory Requirements)
  Purpose:  Find VCPI conventional memory requirements.
  CPU Mode:  Real
  Registers at Call:  None
  Return Registers:  DX:AX = conventional memory requirements.
  Details:
     DX:AX is adjusted upward to an integer multiple of 16.
     This routine simply loads DX:AX with a constant.

  XLIBCONFIG (XLIB Configuration)
  Purpose:  Get XLIB configuration.
  CPU Mode:  Real
  Registers at Call:  None
  Return Registers:  AX = 0 if protected-mode structures are not initialized;
  otherwise, AX = XLIB configuration.  The value of lower nibble identifies the
  protected-mode host/server.  If 1 then DPMI is installed.  If 2 then VCPI is
  installed.  If 3 then XLIB handles mode switches.  Bit 4 is set if XMS is
  installed.



























                                        8






                                4. Mode Switching


       As illustrated in Example 1, CALLPM may be used to transfer control to
  32-bit protected mode in segment TSEG.  When execution is returned to real
  mode, segment registers, ESP, system flags, and control flags are restored to
  their original values.
       Execution may also be transferred to protected mode in TSEG with the
  ENTERPM (enter protected mode) procedure.  This procedure is specially
  designed to accommodate mixed-language programming with high-level languages
  operating in real mode.  High-level language modules may be linked with
  libraries containing protected-mode procedures.  These procedures may then be
  called from high-level code.  However, such procedures must generally be
  careful to restore register state.  ENTERPM restores register state as
  required by Microsoft high-level languages.  In particular, ENTERPM restores
  all registers except EAX, EDX, and the status flags.  EAX and EDX are not
  restored because these are typically used by high-level languages for return
  values.  ENTERPM otherwise functions exactly as CALLPM.
       Both CALLPM and ENTERPM save register state as of call.  CALLPM and
  ENTERPM will also save and restore the state of the floating point unit (FPU)
  if requested.  FPU save/restore can be enabled by setting bit 2 of OFLAGS
  (operation flags).  The bit is clear by default.  OFLAGS is a public WORD in
  DSEG.
       FPU state is saved with the FSAVE instruction executed from real mode.
  This instruction resets the FPU; consequently, the FPU control word must be
  redefined.  XLIB will therefore load FPUCW (FPU control word) to the FPU
  control word after performing FSAVE.  FPUCW is a public WORD location in DSEG.
       After entering protected mode through CALLPM or ENTERPM, control would
  typically be returned to real mode with the RET instruction.  However, control
  may also be returned to real mode by jumping to either RETPM or EXITPM.  These
  are both procedures in TSEG.  They will successfully return control to real
  mode regardless of the stack state.
       RETPM returns control to the real-mode caller of CALLPM/ENTERPM after
  restoring segment registers, ESP, system flags, and control flags.  EXITPM
  returns control to the real mode caller after restoring all registers except
  EAX, EDX, and the status flags.
       The return address placed on the stack by CALLPM is actually a near
  return to RETPM.  Likewise, ENTERPM places a near return to EXITPM.  CALLPM
  and ENTERPM are otherwise identical procedures.
       Once within protected mode, far procedures in real mode can be called
  using CALLRM.  CALLRM may be called only by protected-mode procedures in TSEG.
       XLIB contains two hardware interrupt handlers that are typically
  activated upon entry to protected mode.  These handlers are fully explained in
  Chapter 6.  The first handler is hooked to the keyboard interrupt.  This
  handler manages hot key detection.  The second handler is hooked to the FPU
  interrupt and is designed to handle FPU exceptions.











                                        9






  Detailed Specifications


  CALLPM (Call Protected Mode)
  Purpose:  Call a protected-mode procedure in TSEG with near return.
  CPU Mode:  Real
  Registers at Call:  SS:ESP = 32-bit protected-mode target offset.
  Return Registers:  Returns through RETPM.  See RETPM for details.
  Details:
     All CPU registers except EAX and EDX are saved at locations presented in
  Table 2.  The stack is saved after the return address and argument have been
  popped.
     The target receives SS = TSEGDSEL with 1000H free bytes on the stack.  The
  return address on the stack is a near return to RETPM.  The target receives by
  default:  DS = FLATDSEL, ES = TSEGDSEL, FS = DSEGSEL, and GS = DGROUPSEL.
  Other registers, including the status flags, are received at values as of
  call.
     If bit 2 of OFLAGS is set, then the FPU state is also saved; the FPU is
  initialized, and FPUCW is loaded to the control word.
     XLIB hardware interrupt handlers are enabled (see Chapter 6).  However, if
  bit 1 of OFLAGS is set, then the XLIB interrupt handler for the FPU will not
  be enabled.
     If an FPU exception occurs after CALLPM, and if the FPU exception handler
  is enabled, then protected mode will be exited through EXITPM rather than
  RETPM.  If FPU save/restore is not enabled, then real-mode will receive an
  initialized FPU with control word set to the value existing as of the
  exception.
     The user may change the stack after the mode switch.
     DS, ES, FS, and GS are actually loaded from:  PMDS, PMES, PMFS, and PMGS.
  These are public WORD locations in DSEG and are initialized to the default
  selectors by INITXLIB.  The user however may change these selectors to any
  legal values after initialization.

  RETPM (Return From Protected Mode)
  Purpose:  Return control to real mode with partial register restoration.
  CPU Mode:  Protected
  Registers at Call:  None
  Return Registers:  No return
  Details:
     RETPM switches to real mode and then restores all segment registers, ESP,
  system flags, and control flags to values as of call to either CALLPM or
  ENTERPM.  XLIB hardware interrupt handlers are disabled (see Chapter 6).
  Control is then transferred to the real-mode return address as of call to
  CALLPM/ENTERPM.
     If bit 2 of OFLAGS is set, then RETPM also restores FPU state.
     RETPM will successfully execute regardless of stack state.

  ENTERPM (Enter Protected Mode)
  Purpose:  Call a protected mode procedure in TSEG with near return.
  CPU Mode:  Real
  Registers at Call:  SS:ESP = 32-bit protected-mode target offset.
  Return Registers:  Returns through EXITPM.  See EXITPM for details.
  Details:  This routine executes exactly as CALLPM except that a near return to
  EXITPM is placed on the stack rather than to RETPM.



                                        10







  EXITPM (Exit Protected Mode)
  Purpose:  Return control to real mode with general register restoration.
  CPU Mode:  Protected
  Registers at Call:  None
  Return Registers:  No return
  Details:
     EXITPM switches to real mode and then restores all registers except EAX,
  EDX, and status flags to values as of call to either CALLPM or ENTERPM.  XLIB
  hardware interrupt handlers are disabled (see Chapter 6).  Control is then
  transferred to the real-mode return address as of call to CALLPM/ENTERPM.
     If bit 2 of OFLAGS is set, then EXITPM also restores FPU state.
     EXITPM will successfully execute regardless of stack state.
     The FPU exception handler performs a jump to EXITPM upon occurrence of any
  unmasked FPU exception.


  Table 2:  CALLPM/ENTERPM Register Storage Locations by Public Symbol
  -----------------------------------------------------------------------------
  Register           Symbol              Symbol Type
  --------           ------              -----------
  EBX                ORGEBX              DWORD
  ECX                ORGECX              DWORD
  ESI                ORGESI              DWORD
  EDI                ORGEDI              DWORD
  EBP                ORGEBP              DWORD
  ESP                ORGESP              DWORD
  EFLAGS             ORGEFLAGS           DWORD
  SS                 ORGSS               WORD
  DS                 ORGDS               WORD
  ES                 ORGES               WORD
  FS                 ORGFS               WORD
  GS                 ORGGS               WORD
  FPU State          ORGFPU              BYTE[94]
  -----------------------------------------------------------------------------


  CALLRM (Call a Real-Mode Procedure)
  Purpose:  Call a real-mode routine with far return from protected mode.
  CPU Mode:  Protected
  Registers at Call:  SS:ESP = far real-mode target address (four bytes).
  Return Registers:  All segment registers and ESP are restored.  Other
  registers, including status flags, are received with values as of the real-
  mode RET instruction.
  Details:
     This is a near procedure in TSEG.  It must therefore be called from TSEG.
     Segment registers and ESP are saved at locations presented in Table 3.  The
  stack is saved after popping the return address and argument.
     The target receives the XLIB real-mode stack (SS = DSEG) with 200H free
  bytes.  By default, the target receives DS = DGROUP, ES = DSEG, FS = DSEG, and
  GS = DSEG.  Other registers, including status flags, are received at values as
  of call.
     Code called by this routine should not perform calls to XLIB procedures
  other than SWITCHPM and SWITCHRM (see Appendix G).



                                        11






     DS and ES are actually loaded from RMDS and RMES.  These are public WORD
  locations in DSEG and are initialized to the default values.  However, the
  user may change these values if desired.
     This procedure does not change values in OFLAGS; consequently, XLIB
  hardware interrupt handlers remain enabled in real mode if they were enabled
  as of call (see Chapter 6).
     FPU exceptions in real mode are handled the same as in protected mode;
  however, system software is less apt to be left in regular state after real-
  mode exceptions.  FPU instructions should therefore be executed in protected
  mode where possible.