home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Current Shareware 1994 January
/
SHAR194.ISO
/
sys_util
/
dpmiv1.zip
/
DPMIV1.TXT
Wrap
Text File
|
1993-08-18
|
139KB
|
4,058 lines
Int 2FH Function 1680H [1.0]
Release Current Virtual Machine's Time Slice
Called by a client program to indicate that the program is
idle (for example, waiting for keyboard input). This allows
the DPMI host to pass the CPU to other clients, or take
power-conserving measures on laptop and notebook computers.
Call With:
AX = 1680H
Returns:
if function supported by host
AL = 0
if function not supported by host
AL = unchanged (80H)
Notes:
o This function is not specific to DPMI hosts. Some
operating systems will recognize this call for programs
running in real mode. Programmers are encouraged to use
this call in all DOS and DPMI-client programs. All DPMI
hosts will hook Int 2FH and so a DPMI client can use this
API without any other precautions. Non-DPMI programs
that can run on DOS 2.xx or earlier should make sure that
the Int 2FH vector is non-zero before executing the Int
2FH.
o When an application calls this function it will regain
control at intervals, so it should continue to re-issue
this function call so long as it has nothing to do.
o DPMI client and application vendors are encouraged to use
this function. It can significantly improve the
performance of a DOS-based multitasking host.
Int 2FH Function 1686H [0.9]
Get CPU Mode
Returns information about the current CPU mode. Programs
which only execute in protected mode do not need to call
this function.
Call With:
AX = 1686H
Returns:
if executing in protected mode
AX = 0
if executing in real mode or Virtual 86 mode
AX = nonzero
Notes:
o Some environments support programs or libraries that can
execute in either real or protected mode (bimodal code).
This function is supplied so that such programs can
detect at run time whether they are running in protected
mode and make use of system facilities accordingly.
o This function should not be used to determine if a DPMI
host is present. A client should make sure that DPMI
services are available before calling this function;
otherwise, the results returned by the function may not
be valid.
Int 2FH Function 1687H [0.9]
Obtain Real-to-Protected Mode Switch Entry Point
This function can be called in real mode only to test for
the presence of a DPMI host, and to obtain an address of a
mode switch routine that can be called to begin execution in
protected mode.
Call With:
AX = 1687h
Returns:
if function successful
AX = 0
BX = flags
Bit Significance
0 0 = 32-bit programs are not supported
1 = 32-bit programs are supported
1-15 not used
CL = processor type
02H = 80286
03H = 80386
04H = 80486
05H-FFH Reserved for future Intel processors
DH = DPMI major version as a decimal number
(represented in binary)
DL = DPMI minor version as a decimal number
(represented in binary)
SI = number of paragraphs required for DPMI host
private data (may be 0)
ES:DI = segment:offset of procedure to call to enter
protected mode
if function unsuccessful (no DPMI host present)
AX = nonzero
Notes:
o The entry point returned by Int 2FH Function 1687H is
only called for the first switch to protected mode by a
DPMI client. For further details on the protocol for
switching to protected mode and the environment after
switching to protected mode, see page 22.
o Under DPMI hosts, the major version number is returned in
DH and the minor version number is returned in DL. There
are two decimal digits for the minor version number with
the least-significant digit representing the revision
number of the minor version number. Under DPMI version
0.9 hosts, DH is returned as 0, and DL is returned as
decimal 90 (5AH). In hypothetical DPMI version 2.3, DH
would be returned as 2 and DL would be returned as 30
(1EH).
Int 2FH Function 168AH [1.0]
Get Vendor-Specific API Entry Point
Returns an address which can be called to use host-specific
extensions to the standard set of DPMI functions. This
function is available only in protected mode.
Call With:
AX = 168AH
DS:(E)SI= selector:offset of ASCIIZ (null-terminated)
string identifying the DPMI host vendor
Returns:
if function successful
AL = 0
ES:(E)DI= extended API entry point
and DS, FS, GS, EAX, EBX, ECX, EDX, ESI, and EBP are
preserved.
if function unsuccessful
AL = unchanged (8AH)
Notes:
o The ASCIIZ string specifies a host vendor name or some
other unique identifier to obtain a specific extension
entry point. The string comparison used to look up the
API entry point is case-sensitive.
o Clients must use a FAR CALL to reach the extended API
entry point.
o All extended API parameters are specified by the vendor.
o DPMI 1.0 clients should use this function in preference
to Int 31H Function 0A00H. This method of API extension
is preferable to the Int 31H extension as it avoids the
creation of a long (and consequently slow) chain of Int
31H handlers which would slow down time-critical DPMI
functions. Note that although this function was not
documented for DPMI 0.9, it will work under any DPMI 0.9
host.
Int 31H Function 0000H [0.9]
Allocate LDT Descriptors
Allocates one or more descriptors in the task's Local
Descriptor Table (LDT). The descriptor(s) allocated must be
initialized by the application with other function calls.
Call With:
AX = 0000H
CX = number of descriptors to allocate
Returns:
if function successful
Carry flag= clear
AX = base selector
if function unsuccessful
Carry flag= set
AX = error code
8011H descriptor unavailable
Notes:
o If more than one descriptor was requested, the function
returns a base selector referencing the first of a
contiguous array of descriptors. The selector values for
subsequent descriptors in the array can be calculated by
adding the value returned by Int 31H Function 0003H.
o The allocated descriptor(s) will be set to "data" with
the present bit set and a base and limit of zero. The
privilege level of the descriptor(s) will match the
application's code segment privilege level.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0001H [0.9]
Free LDT Descriptor
Frees an LDT descriptor.
Call With:
AX = 0001H
BX = selector for the descriptor to free
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8022Hinvalid selector
Notes:
o Each descriptor allocated with Int 31H Function 0000H
must be freed individually with this function, even if it
was previously allocated as part of a contiguous array of
descriptors.
o Under DPMI 1.0 hosts, any segment registers which contain
the selector being freed are zeroed by this function.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0002H [0.9]
Segment to Descriptor
Maps a real mode segment (paragraph) address onto an LDT
descriptor that can be used by a protected mode program to
access the same memory.
Call With:
AX = 0002H
BX = real mode segment address
Returns:
if function successful
Carry flag= clear
AX = selector for real mode segment
if function unsuccessful
Carry flag= set
AX = error code
8011H descriptor unavailable
Notes:
o The descriptor's limit will be set to 64 KB.
o Multiple calls to this function with the same segment
address will return the same selector.
o The intent of this function is to provide clients with
easy access to commonly used real mode segments such as
the BIOS data area at segment 0040H and the video refresh
buffers at segments A000H, B000H, and B800H. Clients
should not call this function to obtain descriptors to
private data areas.
o Descriptors created by this function can never be
modified or freed. For this reason, the function should
be used sparingly. Clients which need to examine various
real mode addresses using the same selector should
allocate a descriptor with Int 31H Function 0000H and
change the base address in the descriptor as necessary,
using the Set Segment Base Address function (Int 31H
Function 0007H).
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0003H [0.9]
Get Selector Increment Value
The DPMI functions Allocate LDT Descriptors (Int 31H
Function 0000H) and Allocate DOS Memory Block (Int 31H
Function 0100H) can allocate
an array of contiguous descriptors, but only return a
selector for the first descriptor. The value returned by
this function can be used to calculate the selectors for
subsequent descriptors in the array.
Call With:
AX = 0003H
Returns:
Carry flag= clear (this function always succeeds)
AX = selector increment value
Notes:
o The increment value is always a power of two.
Int 31H Function 0004H [0.9]
Reserved
DPMI Function 0004H is reserved for historical reasons and
should not be called.
Int 31H Function 0005H [0.9]
Reserved
DPMI Function 0005H is reserved for historical reasons and
should not be called.
Int 31H Function 0006H [0.9]
Get Segment Base Address
Returns the 32-bit linear base address from the LDT
descriptor for the specified segment.
Call With:
AX = 0006H
BX = selector
Returns:
if function successful
Carry flag= clear
CX:DX = 32-bit linear base address of segment
if function unsuccessful
Carry flag= set
AX = error code
8022H invalid selector
Notes:
o Client programs must use the LSL instruction to query the
limit for a descriptor. Note that on 80386 machines, the
client must use the 32-bit form of LSL if the segment
size is greater than 64 KB.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0007H [0.9]
Set Segment Base Address
Sets the 32-bit linear base address field in the LDT
descriptor for the specified segment.
Call With:
AX = 0007H
BX = selector
CX:DX = 32-bit linear base address of segment
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8022H invalid selector
8025H invalid linear address (changing the base
would cause the descriptor to reference a
linear address range outside that allowed
for DPMI clients)
Notes:
o A DPMI 1.0 host will automatically reload any segment
register which contains the selector specified in
register BX. It is suggested that DPMI 0.9 hosts also
implement this.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0008H [0.9]
Set Segment Limit
Sets the limit field in the LDT descriptor for the specified
segment.
Call With:
AX = 0008H
BX = selector
CX:DX = 32-bit segment limit
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8021H invalid value (CX <> 0 on a 16-bit DPMI
host; or the limit is greater than 1 MB,
but the low twelve bits are not set)
8022H invalid selector
8025H invalid linear address (changing the
limit would cause the descriptor to
reference a linear address range outside
that allowed for DPMI clients.)
Notes:
o The value supplied to the function in CX:DX is the byte
length of the segment-1 (i.e., the value returned by the
LSL instruction).
o Segment limits greater than or equal to 1 MB must be
page-aligned. That is, limits greater than 1 MB must
have the low 12 bits set.
o This function has an implicit effect on the "G"
(granularity) bit in an 80386 descriptor's extended
access rights/type byte; i.e., it is the host's
responsibility to set the "G" bit correctly.
o Client programs must use the LSL instruction to query the
limit for a descriptor. Note that on 80386 machines, the
client must use the 32-bit form of LSL if the segment
size is greater than 64 KB.
o A DPMI 1.0 host will reload any segment registers which
contain the selector specified in register BX. It is
suggested that DPMI 0.9 hosts also implement this.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0009H [0.9]
Set Descriptor Access Rights
Modifies the access rights and type fields in the LDT
descriptor for the specified segment.
Call With:
AX = 0009H
BX = selector
CL = access rights/type byte
CH = 80386 extended access rights/type byte
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8021H invalid value (access rights/type bytes
invalid)
8022H invalid selector
8025H invalid linear address (changing the
access rights/type bytes would cause the
descriptor to reference a linear address
range outside that allowed for DPMI
clients.)
Notes:
o The access rights/type byte passed to the function in CL
has the following format:
+---+---+---+---+---+---+---+---+
| P | DPL | 1 |C/D|E/C|W/R| A |
+-+-+---+---+-+-+-+-+-+-+-+-+-+-+
| | | | | | |
| | | | | | +- 0=not accessed, 1=accessed
| | | | | +----- data: 0=read,
1=>read/write
| | | | | code: must be 1 (readable)
| | | | +--------- data: 0=expand-up,
1=expand-down
| | | | code: must be 0
(non-conforming)
| | | +------------- 0=data, 1=code
| | +----------------- must be 1
| +----------------------- must equal caller's CPL
+----------------------------- 0=absent, 1=present
If the Present bit is not set in the descriptor, the DPMI
host allows any values except in the DPL and "must be 1"
bit fields.
o On 80386 (and later) machines, the DPMI host interprets
the value passed to the function in CH as follows:
+---+---+---+---+---+---+---+---+
| G |B/D| 0 |Avl| Reserved |
+-+-+-+-+-+-+-+-+---+---+---+---+
| | | | |
| | | | +-- ignored
| | | +------------ can be 0 or 1
| | +---------------- must be 0
| +-------------------- 0=default 16-bit, 1=default
32-bit
+------------------------ 0=byte granular, 1=page
granular
o A DPMI 1.0 host will reload any segment registers which
contain the selector specified in register BX. It is
suggested that DPMI 0.9 hosts also implement this.
o Client programs should use the LAR instruction to examine
the access rights of a descriptor.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 000AH [0.9]
Create Alias Descriptor
Creates a new LDT data descriptor that has the same base and
limit as the specified descriptor.
Call With:
AX = 000AH
BX = selector
Returns:
if function successful
Carry flag= clear
AX = data selector (alias)
if function unsuccessful
Carry flag= set
AX = error code
8011H descriptor unavailable
8022H invalid selector
Notes:
o The selector supplied to the function may be either a
data selector or an executable selector. Note that the
published 0.9 specification was in error to say that the
function generates an error on a data descriptor.
o The descriptor alias returned by this function will not
track changes to the original descriptor. In other
words, if an alias is created with this function, and the
base or limit of the original segment is then changed,
the two descriptors will no longer map the same memory.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 000BH [0.9]
Get Descriptor
Copies the local descriptor table (LDT) entry for the
specified selector into an 8-byte buffer.
Call With:
AX = 000BH
BX = selector
ES:(E)DI= selector:offset of 8-byte buffer
Returns:
if function successful
Carry flag= clear
and buffer pointed to by ES:(E)DI contains descriptor
if function unsuccessful
Carry flag= set
AX = error code
8022H invalid selector
Notes:
o 32-bit programs must use ES:EDI to point to the buffer.
16-bit programs should use ES:DI.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 000CH [0.9]
Set Descriptor
Copies the contents of an 8-byte buffer into the LDT
descriptor for the specified selector.
Call With:
AX = 000CH
BX = selector
ES:(E)DI= selector:offset of 8-byte buffer containing
descriptor
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8021H invalid value (access rights/type byte
invalid)
8022H invalid selector
8025H invalid linear address (descriptor
references a linear address range outside
that allowed for DPMI clients)
Notes:
o 32-bit programs must use ES:EDI to point to the buffer.
16-bit programs should use ES:DI.
o The descriptor's access rights/type byte (byte 5) follows
the same format and restrictions as the access
rights/type parameter (in CL) for the Set Descriptor
Access R
ights function (Int 31H Function 0009H). On 80386 (or later)
machines, the descriptor's extended access rights/type
byte (byte 6) follows the same format and restrictions as
the extended access rights/type parameter (in CH) for the
same function, except the low-order 4 bits (marked
"reserved") are used to set the upper 4 bits of the
descriptor's limit.
o If the descriptor's present bit is not set, then the only
error checking is that the client's CPL must be equal to
the descriptor's DPL field and the "must be 1" bit in the
descriptor's byte 5 must be set.
o A DPMI 1.0 host will reload any segment register which
contains a selector specified in register BX. It is
suggested that DPMI 0.9 hosts also implement this.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 000DH [0.9]
Allocate Specific LDT Descriptor
Allocates a specific LDT descriptor.
Call With:
AX = 000DH
BX = selector
Returns:
if function successful
Carry flag= clear
and descriptor has been allocated
if function unsuccessful
Carry flag= set
AX = error code
8011H descriptor unavailable (descriptor is in
use)
8022H invalid selector (references GDT or
beyond the LDT limit)
Notes:
o The first 10H (16) descriptors (selector values 04H-7CH)
are reserved for this function and must not be used by
the DPMI host.
o Under DPMI 0.9 hosts, if another application has already
been loaded, some of descriptors reserved for allocation
by this function may be already in use and unavailable.
Under DPMI 1.0 hosts, each client has its own LDT and
thus will have the full 16 descriptors available for use
with this function.
o Resident service providers (protected-mode TSRs) should
not use this function.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 000EH [1.0]
Get Multiple Descriptors
Copies one or more local descriptor table (LDT) entries into
a client buffer.
Call With:
AX = 000EH
CX = number of descriptors to copy
ES:(E)DI= selector:offset of a buffer in the following
format:
Offset Length Contents
00H 2 Selector #1 (set by client)
02H 8 Descriptor #1 (returned by
host)
0AH 2 Selector #2 (set by client)
0CH 8 Descriptor #2 (returned by
host)
. . .
. . .
. . .
Returns:
if function successful
Carry flag= clear
and buffer contains copies of the descriptors for the
specified selectors
if function unsuccessful
Carry flag= set
AX = error code
8022H invalid selector
CX = number of descriptors successfully copied
Notes:
o If an error occurs because of an invalid selector or
descriptor, the function returns the number of
descriptors which were successfully copied in CX. All of
the descriptors which were copied prior to the one that
failed are valid.
o 32-bit programs must use ES:EDI to point to the buffer.
16-bit programs should use ES:DI.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 000FH [1.0]
Set Multiple Descriptors
Copies one or more descriptors from a client buffer into the
local descriptor table (LDT).
Call With:
AX = 000FH
CX = number of descriptors to copy
ES:(E)DI= selector:offset of a buffer in the following
format:
Offset Length Contents
00H 2 Selector #1
02H 8 Descriptor #1
0AH 2 Selector #2
0CH 8 Descriptor #2
. . .
. . .
. . .
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8021H invalid value (access rights/type bytes
invalid)
8022H invalid selector 8025H invalid linear
address (descriptor references a linear
address range outside that allowed for
DPMI clients)
CX = number of descriptors successfully copied
Notes:
o If an error occurs because of an invalid selector or
descriptor, the function returns the number of
descriptors which were successfully copied in CX. All of
the descriptors which were copied prior to the one that
failed are valid. All descriptors from the invalid entry
to the end of the table are not updated.
o 32-bit programs must use ES:EDI to point to the buffer.
16-bit programs should use ES:DI.
o A descriptor's access rights/type byte (byte 5) follows
the same format and restrictions as the access
rights/type parameter (in CL) for the Set Descriptor
Access Rights function (Int 31H Function 0009H). On
80386 (or later) machines, the descriptor's extended
access rights/type byte (byte 6) follows the same format
and restrictions as the extended access rights/type
parameter (in CH) for the same function, except the
low-order 4 bits (marked "reserved") are used to set the
upper 4 bits of the descriptor's limit.
o If the descriptor's present bit is not set, then the only
error checking is that the client's CPL must be equal to
the descriptor's DPL field and the "must be 1" bit in the
descriptor's byte 5 must be set.
o A DPMI 1.0 host will reload any segment register which
contains a selector specified in the data structure
supplied to this function. It is suggested that DPMI 0.9
hosts also implement this.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0100H [0.9]
Allocate DOS Memory Block
Allocates a block of memory from the DOS memory pool, i.e.
memory below the 1 MB boundary that is controlled by DOS.
Such memory blocks are typically used to exchange data with
real mode programs, TSRs, or device drivers. The function
returns both the real mode segment base address of the block
and one or more descriptors that can be used by protected
mode applications to access the block.
Call With:
AX = 0100H
BX = number of (16-byte) paragraphs desired
Returns:
if function successful
Carry flag= clear
AX = real mode segment base address of allocated
block
DX = selector for allocated block
if function unsuccessful
Carry flag= set
AX = error code
0007H memory control blocks damaged (also
returned by DPMI 0.9 hosts)
0008H insufficient memory (also returned by
DPMI 0.9 hosts).
8011H descriptor unavailable
BX = size of largest available block in paragraphs
Notes:
o If the size of the block requested is greater than 64 KB
(BX > 1000H) and the client is a 16-bit program,
contiguous descriptors are allocated and the base
selector is returned. The consecutive selectors for the
memory block can be calculated using the value returned
by the Get Selector Increment Value function (Int 31H
Function 0003H). Each descriptor has a limit of 64 KB,
except for the last which has a limit of blocksize MOD 64
KB.
o If the DPMI host is 32-bit, the client is 16-bit, and
more than one descriptor is allocated, the limit of the
first descriptor will be set to the size of the entire
block. Subsequent descriptors have limits as described
in the previous Note. 16-bit DPMI hosts will always set
the limit of the first descriptor to 64 KB even when
running on an 80386 (or later) machine.
o When the client is 32-bit, this function always allocates
only one descriptor.
o Client programs should never modify or free any
descriptors allocated by this function. The Free DOS
Memory Block function (Int 31H Function 0101H) will
deallocate the descriptors automatically.
o The DOS allocation function (Int 21H Function 48H) is
used.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0101H [0.9]
Free DOS Memory Block
Frees a memory block that was previously allocated with the
Allocate DOS Memory Block function (Int 31H Function 0100H).
Call With:
AX = 0101H
DX = selector of block to be freed
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
0007H memory control blocks damaged (also
returned by DPMI 0.9 hosts).
0009H incorrect memory segment specified (also
returned by DPMI 0.9 hosts).
8022H invalid selector
Notes:
o All descriptors allocated for the memory block are
automatically freed by this function, and are no longer
valid after this function returns.
o Under DPMI 1.0 hosts, any segment registers which contain
a selector being freed are zeroed by this function.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0102H [0.9]
Resize DOS Memory Block
Changes the size of a memory block that was previously al
located with the Allocate DOS Memory Block function (Int 31H
Function 0100H).
Call With:
AX = 0102H
BX = new block size in (16-byte) paragraphs
DX = selector of block to modify
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
0007H memory control blocks damaged (also
returned by DPMI 0.9 hosts).
0008H insufficient memory (also returned by
DPMI 0.9 hosts).
0009H incorrect memory segment specified (also
returned by DPMI 0.9 hosts).
8011H descriptor unavailable
8022H invalid selector
BX = maximum possible block size (paragraphs)
Notes:
o Requests to increase the size of an existing DOS memory
block may fail due to subsequent DOS memory block
allocations causing fragmentation of DOS memory, or
insufficient remaining DOS memory. In addition, the
function will fail if the block is growing past a 64 KB
boundary and the next descriptor in the LDT is not
available.
o A request to decrease the size of a DOS memory block may
cause some descriptors that were previously allocated to
the block to be freed and the limit of the new last
descriptor for the block to be changed.
o Under a DPMI 1.0 host, any segment registers which
contain a selector being modified are reloaded by this
function and any segment registers which contain a
selector being freed are zeroed by this function.
o Client programs should never modify or free any
descriptors allocated by this function. The Free DOS
Memory Block function (Int 31H Function 0101H) will
deallocate the descriptors automatically.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0200H [0.9]
Get Real Mode Interrupt Vector
Returns the contents of the current virtual machine's real
mode interrupt vector for the specified interrupt.
Call With:
AX = 0200H
BL = interrupt number
Returns:
Carry flag= clear (this function always succeeds)
CX:DX = segment:offset of real mode interrupt handler
Notes:
o The value returned in CX is a real mode segment address,
not a selector. Attempts to place this value into a
segment register in protected mode may cause a general
protection (GP) fault.
o All 100H (256) real mode interrupt vectors must be made
available through this function by the DPMI host.
Int 31H Function 0201H [0.9]
Set Real Mode Interrupt Vector
Sets the current virtual machine's real mode interrupt
vector for the specified interrupt.
Call With:
AX = 0201H
BL = interrupt number
CX:DX = segment:offset of real mode interrupt handler
Returns:
Carry flag= clear (this function always succeeds)
Notes:
o The address passed in CX must be a real mode segment
address, not a selector. Consequently, the interrupt
handler must either reside in DOS memory (i.e. below the
1 MB boundary) or the client must allocate a real mode
callback address. See Int 31H Functions 0100H and 0303H.
o If the interrupt being hooked is a hardware interrupt,
the memory that the interrupt handler uses must be
locked.
Int 31H Function 0202H [0.9]
Get Processor Exception Handler Vector
Returns the address of the current client's protected mode
exception handler for the specified exception number. This
function should be avoided by DPMI 1.0 clients (see Notes).
Call With:
AX = 0202H
BL = exception number (00H-1FH)
Returns:
if function successful
Carry flag= clear
CX:(E)DX= selector:offset of exception handler
if function unsuccessful
Carry flag= set
AX = error code
8021H invalid value (BL not in range 0-1FH)
Notes:
o The value returned in CX is a valid protected mode
selector, not a real mode segment address.
o 32-bit clients will be returned a 32-bit offset in the
EDX register.
o Clients which run under DPMI 1.0 should use Int 31H
Functions 0210H and 0211H to obtain the addresses of
exception handlers. This function is supported by DPMI
1.0 hosts solely for compatibility with DPMI 0.9.
Int 31H Function 0203H [0.9]
Set Processor Exception Handler Vector
Sets the address of a handler for a CPU exception or fault,
allowing a protected mode application to intercept processor
exceptions (such as segment not present faults) that are not
handled by the DPMI host and would otherwise generate a
fatal error. This function should be avoided by DPMI 1.0
clients (see Notes).
Call With:
AX = 0203H
BL = exception/fault number (00H-1FH)
CX:(E)DX= selector:offset of exception handler
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8021H invalid value (BL not in range 0-1FH)
8022H invalid selector
Notes:
o The value passed in CX should be a valid protected mode
code (executable) selector, not a real mode segment
address.
o 32-bit clients must supply a 32-bit offset in the EDX
register. If the client's handler chains to the next
exception handler, it must do so using a 32-bit interrupt
stack frame.
o Every exception is first examined by the DPMI host. If
the host does not handle the exception, it reflects the
exception to the first handler in the protected mode
exception handler chain. See page 30 for a complete
discussion of the environment and responsibilities of
protected mode exception handlers installed with this
function.
o Clients which run under DPMI 1.0 should use Int 31H
Functions 0212H and 0213H to set the addresses of
exception handlers. This function is supported by DPMI
1.0 hosts solely for compatibility with DPMI 0.9.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0204H [0.9]
Get Protected Mode Interrupt Vector
Returns the address of the current protected mode interrupt
handler for the specified interrupt.
Call With:
AX = 0204H
BL = interrupt number
Returns:
Carry flag= clear (this function always succeeds)
CX:(E)DX= selector:offset of exception handler
Notes:
o The value returned in CX is a valid protected mode
selector, not a real mode segment address.
o 32-bit clients will be returned a 32-bit offset in the
EDX register.
o DPMI hosts must make all 100H (256) interrupt vectors
available through this function.
Int 31H Function 0205H [0.9]
Set Protected Mode Interrupt Vector
Sets the address of protected mode handler for the specified
interrupt into the interrupt vector.
Call With:
AX = 0205H
BL = interrupt number
CX:(E)DX= selector:offset of exception handler
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8022H invalid selector
Notes:
o The value passed in CX should be a valid protected mode
code selector, not a real mode segment address.
o 32-bit clients must supply a 32-bit offset in the EDX
register. If the client's handler chains to the next
exception handler it must do so using a 32-bit interrupt
stack frame.
o DPMI hosts must support all 100H (256 decimal) interrupt
vectors with this function.
o Hardware interrupts are sent to the primary client of the
virtual machine while software interrupts are sent to the
current client. (See Appendix A: Glossary for definitions
of primary and current client.)
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0210H [1.0]
Get Extended Processor Exception Handler Vector
(Protected Mode)
Returns the address of the client's protected mode handler
for the specified protected mode exception.
Call With:
AX = 0210H
BL = exception number (00H-1FH)
Returns:
if function successful
Carry flag= clear
CX:(E)DX= selector:offset of exception handler
if function unsuccessful
Carry flag= set
AX = error code
8021H invalid value (BL not in range 00H-1FH)
Notes:
o DPMI 1.0 clients should use this function in preference
to Int 31H Function 0202H.
o The protected mode exceptions are sent to the protected
mode handler of the current client. (See Appendix A:
Glossary for definition of primary client.)
Int 31H Function 0211H [1.0]
Get Extended Processor Exception Handler Vector
(Real Mode)
Returns the address of the client's protected mode handler
for the specified real mode exception.
Call With:
AX = 0211H
BL = exception number (00H-1FH)
Returns:
if function successful
Carry flag= clear
CX:(E)DX= selector
:offset of exception handler
if function unsuccessful
Carry flag= set
AX = error code
8021H invalid value (BL not in range 00H-1FH)
Notes:
o CX:(E)DX does not specify a real-mode segment:offset.
The reason is that this function allows a client to get
the address of the exception handler which will receive
control in protected mode when the specified exception
occurs in real mode (i.e. the host will provide an
implied mode switch for the purposes of servicing the
exception, then return to real mode after the handler
exits)..
o Real mode exceptions are sent to the primary client of
the virtual machine.
Int 31H Function 0212H [1.0]
Set Extended Processor Exception Handler Vector
(Protected Mode)
Sets the address of the client's protected mode handler for
the specified protected mode exception.
Call With:
AX = 0212H
BL = exception/fault number (00H-1FH)
CX:(E)DX= selector:offset of exception handler
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8021H invalid value (BL not in range 00H-1FH)
8022H invalid selector
Notes:
o DPMI 1.0 clients should use this function in preference
to Int 31H Function 0203H.
o The protected mode exceptions are sent to the protected
mode handler of the current client.
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0213H [1.0]
Set Extended Processor Exception Handler Vector
(Real Mode)
Sets the address of the client's protected mode handler for
the specified real mode exception.
Call With:
AX = 0213H
BL = exception/fault number (00H-1FH)
CX:(E)DX= selector:offset of exception handler
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8021H invalid value (BL not in range 00H-1FH)
8022H invalid selector
Notes:
o CX:(E)DX does not specify a real-mode segment:offset.
The reason is that this function allows a client to set
the address of an exception handler which will receive
control in protected mode when the specified exception
occurs in real mode (i.e. the host will provide an
implied mode switch for the purposes of servicing the
exception, then return to real mode after the handler
exits).
o Real mode exceptions are sent to the primary client of
the virtual machine. (See Appendix A: Glossary for
definition of primary client.)
o Refer to the rules for descriptor usage in Appendix D.
Int 31H Function 0300H [0.9]
Simulate Real Mode Interrupt
Simulates an interrupt in real mode. The function transfers
control to the address specified by the real mode interrupt
vector. The real mode handler must return by executing an
IRET.
Call With:
AX = 0300H
BL = interrupt number
BH = flags
Bit Significance
0 reserved for historical reason, must be
zero
1-7 reserved, must be zero
CX = number of words to copy from protected mode to
real mode stack
ES:(E)DI= selector:offset of real mode register data
structure in the following format:
Offset Length Contents
00H 4 DI or EDI
04H 4 SI or ESI
08H 4 BP or EBP
0CH 4 reserved, should be zero
10H 4 BX or EBX
14H 4 DX or EDX
18H 4 CX or ECX
1CH 4 AX or EAX
20H 2 CPU status flags
22H 2 ES
24H 2 DS
26H 2 FS
28H 2 GS
2AH 2 IP (reserved, ignored)
2CH 2 CS (reserved, ignored)
2EH 2 SP
30H 2 SS
Returns:
if function successful
Carry flag= clear
ES:(E)DI= selector:offset of modified real mode register
data structure
if function unsuccessful
Carry flag= set
AX = error code
8012H linear memory unavailable (stack)
8013H physical memory unavailable (stack)
8014H backing store unavailable (stack)
8021H invalid value (CX too large)
Notes:
o 32-bit programs must use ES:EDI to point to the real mode
register data structure. 16-bit programs should use
ES:DI.
o The CS:IP in the real mode register data structure is
ignored by this function. The appropriate interrupt
handler will be called based on the value passed in BL.
o If the SS:SP fields in the real mode register data
structure are zero, a real mode stack will be provided by
the DPMI host. Otherwise, the real mode SS:SP will be
set to the specified values before the interrupt handler
is called.
o The flags specified in the real mode register data
structure will be pushed on the real mode stack's IRET
frame. The interrupt handler will be called with the
interrupt and trace flags clear.
o Values placed in the segment register positions of the
data structure must be valid for real mode; i.e. the
values must be paragraph addresses and not selectors.
o All general register fields in the data structure are
DWORDs so that 32-bit registers can be passed to real
mode. Note, however, that 16-bit hosts are not required
to pass the high word of 32-bit general registers or the
FS and GS segment registers to real mode even when
running on an 80386 or later CPU.
o The target real mode handler 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.
o When this function returns, the real mode register data
structure will contain the values that were returned by
the real mode interrupt handler.
o It is the caller's responsibility to remove any
parameters that were pushed on the protected mode stack.
Int 31H Function 0301H [0.9]
Call Real Mode Procedure With Far Return Frame
Simulates a FAR CALL to a real mode procedure. The called
procedure must return by executing a RETF (far return)
instruction.
Call With:
AX = 0301H
BH = flags
Bit Significance
0 reserved for historical reason, must be
zero
1-7 reserved, must be zero
CX = number of words to copy from protected mode to
real mode stack
ES:(E)DI= selector:offset of real mode register data
structure in the following format:
Offset Length Contents
00H 4 DI or EDI
04H 4 SI or ESI
08H 4 BP or EBP
0CH 4 reserved, ignored
10H 4 BX or EBX
14H 4 DX or EDX
18H 4 CX or ECX
1CH 4 AX or 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
Returns:
if function successful
Carry flag= clear
ES:(E)DI= selector:offset of modified real mode register
data structure
if function unsuccessful
Carry flag= set
AX = error code
8012H linear memory unavailable (stack)
8013H physical memory unavailable (stack)
8014H backing store unavailable (stack)
8021H invalid value (CX too large)
Notes:
o 32-bit programs must use ES:EDI to point to the real mode
register data structure. 16-bit programs should use
ES:DI.
o The CS:IP in the real mode register data structure
specifies the address of the real mode procedure to call.
o If the SS:SP fields in the real mode register data
structure are zero, a real mode stack will be provided by
the DPMI host. Otherwise, the real mode SS:SP will be
set to the specified values before the interrupt handler
is called.
o Values placed in the segment register positions of the
data structure must be valid for real mode; i.e. the
values must be paragraph addresses and not selectors.
o All general register fields in the data structure are
DWORDs so that 32-bit registers can be passed to real
mode. Note, however, that 16-bit hosts are not required
to pass the high word of 32-bit general registers or the
FS and GS segment registers to real mode even when
running on an 80386 or later CPU.
o 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 exit with a RETF (far return) and should not
clear the stack of any other parameters that were passed
to it on the stack.
o When this function returns, the real mode register data
structure will contain the values that were returned by
the real mode procedure.
o It is the caller's responsibility to remove any
parameters that were pushed on the protected mode stack.
Int 31H Function 0302H [0.9]
Call Real Mode Procedure With IRET Frame
Simulates a FAR CALL w
ith flags pushed on the stack to a real mode procedure. The
real mode routine must return by executing an IRET
instruction.
Call With:
AX = 0302H
BH = flags
Bit Significance
0 reserved for historical reason, must be
zero
1-7 reserved, must be zero
CX = number of words to copy from protected mode to
real mode stack
ES:(E)DI= selector:offset of real mode register data
structure in the following format:
Offset Length Contents
00H 4 DI or EDI
04H 4 SI or ESI
08H 4 BP or EBP
0CH 4 reserved, ignored
10H 4 BX or EBX
14H 4 DX or EDX
18H 4 CX or ECX
1CH 4 AX or 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
Returns:
if function successful
Carry flag= clear
ES:(E)DI= selector:offset of modified real mode register
data structure
if function unsuccessful
Carry flag= set
AX = error code
8012H linear memory unavailable (stack)
8013H physical memory unavailable (stack)
8014H backing store unavailable (stack)
8021H invalid value (CX too large)
Notes:
o 32-bit programs must use ES:EDI to point to the real mode
register data structure. 16-bit programs should use
ES:DI.
o The CS:IP in the real mode register data structure
specifies the address of the real mode procedure to call.
o If the SS:SP fields in the real mode register data
structure are zero, a real mode stack will be provided by
the DPMI host. Otherwise, the real mode SS:SP will be
set to the specified values before the interrupt handler
is called.
o The flags specified in the real mode register data
structure will be pushed on the real mode stack's IRET
frame. The procedure will be called with the interrupt
and trace flags clear.
o Values placed in the segment register positions of the
data structure must be valid for real mode; i.e. the
values must be paragraph addresses and not selectors.
o All general register fields in the data structure are
DWORDs so that 32-bit registers can be passed to real
mode. Note, however, that 16-bit hosts are not required
to pass the high word of 32-bit general registers or the
FS and GS segment registers to real mode even when
running on an 80386 or later CPU.
o The target real mode handler or 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) .
o When this function returns, the real mode register data
structure will contain the values that were returned by
the real mode procedure.
o It is the caller's responsibility to remove any
parameters that were pushed on the protected mode stack.
Int 31H Function 0303H [0.9]
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, or TSR, so that the real mode program can call
procedures within the protected mode program or notify the
protected mode program of an event.
Call With:
AX = 0303H
DS:(E)SI= selector:offset of protected mode procedure to
call
ES:(E)DI= selector:offset of 32H-byte buffer for real
mode register data structure to be used when
calling callback routine.
Returns:
if function successful
Carry flag= clear
CX:DX = segment:offset of real mode callback
if function unsuccessful
Carry flag= set
AX = error code
8015H callback unavailable
Notes:
o DPMI hosts must provide a minimum of 16 callback
addresses per client.
o 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 use the Free
Real Mode Callback Address function (Int 31H Function
0304H) to release a callback that it is no longer using.
o For further information on writing real mode callback
procedures, see page 34.
o The contents of the real mode register data structure is
not valid after the function call, but only at the time
of the actual callback.
Int 31H Function 0304H [0.9]
Free Real Mode Callback Address
Releases a real mode callback address that was previously
allocated with the Allocate Real Mode Callback Address
function (Int 31H Function 0303H).
Call With:
AX = 0304H
CX:DX = real mode callback address to be freed
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8024H invalid callback address
Notes:
o Real mode callbacks are a limited system resource. A
client should release any callback that it is no longer
using.
Int 31H Function 0305H [0.9]
Get State Save/Restore Addresses
Returns the addresses of two procedures used to save and
restore the state of the current task's registers in the
mode which is not currently executing.
Call With:
AX = 0305H
Returns:
Carry flag = clear (this function always succeeds)
AX = size of buffer in bytes required to save state
BX:CX = real mode address of routine used to
save/restore state
SI:(E)DI= protected mode address of routine used to
save/restore state
Notes:
o The real mode address returned by this function in BX:CX
is called only in real mode to save/restore the state of
the protected mode registers. The protected mode address
returned by this function in SI:(E)DI is called only in
protected mode to save/restore the state of the real mode
registers; 16-bit programs should call the address in
SI:DI, 32-bit programs should call the address in SI:EDI.
Registers for the current mode can be saved by simply
pushing them on the stack.
o Both of the state-save 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-save buffer
The state-save 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. For a further
discussion of use of the state save/restore procedures,
see page 25.
o Some DPMI hosts will not require the state to be saved,
indicating this by returning a buffer size of zero in AX.
In such cases, the addresses returned by this function
can still be called, although they will simply return
without performing any useful function.
o Clients do not need to call the state save/restore
procedures before using Int 31H Functions 0300H, 0301H,
or 0302H. The state save/restore procedures are provided
specifically for clients that use the raw mode switch
services.
o A client can use the function to save its state in the
destination mode before switching modes using the raw
mode switch or issuing real-mode calls from a protected
mode hardware interrupt handler. Refer to page 24 for the
detailed information on stacks and mode switching.
Int 31H Function 0306H [0.9]
Get Raw Mode Switch Addresses
Returns addresses that can be called for low-level mode
switching.
Call With:
AX = 0306H
Returns:
Carry flag = clear (this function always succeeds)
BX:CX = real-to-protected mode switch address
SI:(E)DI= protected-to-real mode switch address
Notes:
o The address returned in BX:CX must only be called in real
mode to switch into protected mode. The address returned
in SI:(E)DI must only be called in protected mode to
switch into real mode; 16-bit programs should call the
address returned by this function in SI:DI, while 32-bit
programs should call the address returned in SI:EDI.
o 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
specified 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 th
e segment registers must be appropriate for the destination mode; if
invalid selectors are supplied when switching into
protected mode, an exception will occur.
The values in (E)AX, (E)BX, (E)CX, (E)DX, (E)SI, and (E)DI after the
mode switch are undefined. (E)BP will be preserved across
the mode switch call so it can be used as a pointer. On
an 80386 or later CPU, the FS and GS segment registers
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 DPMI host (even
temporarily).
o It is up to the client to save and restore the state of
the task when using this function to switch modes. This
usually requires using the state save/restore procedures
whose addresses are returned by Int 31H Function 0305H
(see page 94).
o Clients may find it more convenient to use Int 31H
Functions 0300H, 0301H, and 0302H for mode switching than
this function.
Int 31H Function 0400H [0.9]
Get Version
Returns the version number of the DPMI Specification
implemented by the DPMI host. Clients can use this
information to determine which function calls are supported
in the current environment.
Call With:
AX = 0400H
Returns:
Carry flag= clear (this function always succeeds)
AH = DPMI major version as a binary number
AL = DPMI minor version as a binary number
BX = flags
Bits Significance
0 0 = host is 16-bit DPMI implementation
1 = host is 32-bit (80386) DPMI
implementation
1 0 = CPU returned to Virtual 86 mode for
reflected interrupts
1 = CPU returned to real mode for
reflected interrupts
2 0 = virtual memory not supported
1 = virtual memory supported
3 reserved, for historical reasons
4-15 reserved for later use
CL = processor type
02H = 80286
03H = 80386
04H = 80486
05H-FFH reserved for future Intel
processors
DH = current value of virtual master PIC base
interrupt
DL = current value of virtual slave PIC base
interrupt
Notes:
o Under DPMI hosts, the major version number is returned in
DH and the minor version number is returned in DL. There
are two decimal digits for the minor version number with
the least-significant digit representing the revision
number of the minor version number. Under DPMI version
0.9 hosts, DH is returned as 0, and DL is returned as
decimal 90 (5AH). In hypothetical DPMI version 2.3, DH
would be returned as 2 and DL would be returned as 30
(1EH).
Int 31H Function 0401H [1.0]
Get DPMI Capabilities
Returns information about the capabilities of the DPMI host,
including its support or lack of support for optional
features in the DPMI Specification. Clients can use this
information to optimize their use of system resources in the
current environment.
Call With:
AX = 0401H
ES:(E)DI= selector:offset of 128-byte buffer
Returns:
if function successful
Carry flag= clear (this function always succeeds in DPMI
1.0)
AX = capabilities flags
Bits Significance
0 0 = PAGED ACCESSED/DIRTY capability not
supported
1 = PAGED ACCESSED/DIRTY capability
supported
1 0 = EXCEPTIONS RESTARTABILITY capability
not supported
1 = EXCEPTIONS RESTARTABILITY capability
supported
2 0 = DEVICE MAPPING capability not
supported
1 = DEVICE MAPPING capability supported
3 0 = CONVENTIONAL MEMORY MAPPING
capability not supported
1 = CONVENTIONAL MEMORY MAPPING
capability supported
4 0 = DEMAND ZERO-FILL capability not
supported
1 = DEMAND ZERO-FILL capability supported
5 0 = WRITE-PROTECT CLIENT capability not
supported
1 = WRITE-PROTECT CLIENT capability
supported
6 0 = WRITE-PROTECT HOST capability not
supported
1 = WRITE-PROTECT HOST capability
supported
7-15 reserved
CX = reserved, must be 0
DX = reserved, must be 0
ES:(E)DI = selector:offset of 128-byte buffer filled in
by host with information as follows:
Offset Length Contents
0 1 Host major version number as a
decimal number
1 1 Host minor version number as a
decimal number
2 1-126 ASCIIZ (null-terminated) string
identifying the DPMI host
vendor
if function unsuccessful
Carry flag= set (this function always fails in DPMI 0.9)
Notes:
o PAGE ACCESSED/DIRTY capability means the DPMI host
maintains page dirty and accessed bits that can be read
and written with the Get and Set Page Attributes
functions (Int 31H Functions 0506H and 0507H). This
capability must be supported, and must read and write the
hardware-level dirty and accessed bits, if the DPMI host
does not provide demand-paged virtual memory. If the
DPMI host does support virtual memory, this capability is
optional, and if present gives the client the ability to
read and write virtual page dirty and accessed bits
maintained by the host.
o EXCEPTION RESTARTABILITY capability means that a faulting
instruction inside the host kernel can always be
restarted if the client's exception handler corrects the
reason for the exception and returns. Exception
restartability allows a client to provide virtual memory
under a DPMI host without virtual memory, or to support
memory-mapped files under any DPMI host.
o DEVICE MAPPING capability means that the DPMI host
supports the optional Map Device function (Int 31H
Function 0508H).
o CONVENTIONAL MEMORY MAPPING capability means that the
DPMI host supports the optional Map Conventional Memory
function (Int 31H Function 0509H).
o DEMAND ZERO-FILL capability means the DPMI host
guarantees that all committed pages are initialized to
zero when they are created. If this capability is not
supported, the contents of newly committed pages are
undefined.
o WRITE-PROTECT CLIENT capability means the DPMI host
guarantees that the client is running at a privilege
level such that write protection of pages is effective
for the client's accesses and will geneate page faults.
o WRITE-PROTECT HOST capability means the DPMI host
guarantees that the host has configured the system such
that write protection of pages is effective for the
host's accesses and will generate page faults.
o The host major and minor version numbers are OEM-specific
and are not the DPMI version numbers.
Int 31H Function 0500H [0.9]
Get Free Memory Information
Returns information about the amount of available physical
memory, linear address space, and disk space for page
swapping. Since DPMI clients will often run in multitasking
environments, the information returned by this function
should only be considered as advisory. DPMI 1.0 clients
should avoid use of this function (see the last note of the
call).
Call With:
AX = 0500H
ES:(E)DI= selector:offset of 48-byte buffer
Returns:
Carry flag= clear (this function always succeeds)
and the buffer is filled in with the following
information:
Offset Length Contents
00H 4 Largest available free block in bytes
04H 4 Maximum unlocked page allocation in pages
08H 4 Maximum locked page allocation in pages
0CH 4 Linear address space size in pages
10H 4 Total number of unlocked pages
14H 4 Total number of free pages
18H 4 Total number of physical pages
1CH 4 Free linear address space in pages
20H 4 Size of paging file/partition in pages
24H 0CH Reserved, all bytes set to 0FFH
Notes:
o 32-bit programs must use ES:EDI to point to the buffer.
16-bit programs should use ES:DI.
o Only the first field of the returned structure is
guaranteed to contain a valid value. Any fields that are
not supported by the DPMI host will be set by the host to
-1 (0FFFFFFFFH) to indicate that the information is not
available.
o The field at buffer offset 00H specifies the largest
block of contiguous linear memory in bytes that could be
allocated if the memory were to be allocated and left
unlocked.
o The field at buffer offset 04H specifies the largest
number of pages that could be allocated (the value at
offset 00H divided by the page size).
o The field at buffer offset 08H specifies the largest
block of memory in pages that could be allocated and then
locked.
o The field at buffer offset 0CH specifies the size of the
total linear address space in pages. This value includes
all linear address space that has already been allocated.
o The field at buffer offset 10H specifies the total number
of pages that are currently un
locked and could be paged out. This value also contains any free
pages.
o The field at buffer offset 14H specifies the number of
physical pages that currently are not in use.
o The field at offset 18H specifies the total number of
physical pages that the DPMI host manages. This value
includes all free, locked, and unlocked physical pages.
o The field at offset 20H specifies the size of the DPMI
host's paging partition or file in pages.
o The size of the pages used by the DPMI host can be
obtained with the Get Page Size function (Int 31H
Function 0604H).
o DPMI 1.0 clients should use Int 31H Function 050BH in
preference to this function. This function is supported
in DPMI 1.0 solely for backward compatibility with DPMI
0.9.
Int 31H Function 0501H [0.9]
Allocate Memory Block
Allocates and commits a block of linear memory.
Call With:
AX = 0501H
BX:CX = size of block (bytes, must be nonzero)
Returns:
if function successful
Carry flag= clear
BX:CX = linear address of allocated memory block
SI:DI = memory block handle (used to resize and free
block)
if function unsuccessful
Carry flag= set
AX = error code
8012H linear memory unavailable
8013H physical memory unavailable
8014H backing store unavailable
8016H handle unavailable
8021H invalid value (BX:CX = 0)
Notes:
o The allocated block is guaranteed to have at least
paragraph alignment.
o This function always creates committed pages.
o This function does not allocate any descriptors for the
memory block. It is the responsibility of the client to
allocate and initialize any descriptors needed to access
the memory with additional DPMI function calls.
o Under DPMI hosts that support virtual memory, the memory
block will be allocated unlocked. The client can lock
some or all of the memory after it is allocated with the
Lock Linear Region function (Int 31H Function 0600H).
o Under many DPMI hosts, allocations by this function are
page granular. This means, for example, that if the DPMI
host uses a page size of 4 KB (1000H), an allocation of
1001H bytes will actually result in an allocation of
2000H bytes. Therefore, it is best to always allocate
memory in multiples of the unit of granularity (under
DPMI 0.9, use 4K bytes), which can be obtained with Int
31H Function 0604H.
Int 31H Function 0502H [0.9]
Free Memory Block
Frees a memory block that was previously allocated with
either the Allocate Memory Block function (Int 31H Function
0501H) or the Allocate Linear Memory Block function (Int 31H
Function 0504H).
Call With:
AX = 0502H
SI:DI = memory block handle
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8023H invalid handle
Notes:
o This call will correctly free all of the possible page
types that can occur in a memory block: committed pages,
uncommitted pages, and mapped pages (see Appendix A:
Glossary).
o No descriptors are freed by this call. It is the
client's responsibility to free any descriptors that it
previously allocated to map the memory block.
Descriptors should be freed before linear memory blocks.
Int 31H Function 0503H [0.9]
Resize Memory Block
Changes the size of a memory block that was previously
allocated with either the Allocate Memory Block function
(Int 31H Function 0501H) or the Allocate Linear Memory Block
function (Int 31H Function 0504H).
Call With:
AX = 0503H
BX:CX = new size of block (bytes, must be nonzero)
SI:DI = memory block handle
Returns:
if function successful
Carry flag= clear
BX:CX = new linear address of memory block
SI:DI = new handle for memory block
if function unsuccessful
Carry flag= set
AX = error code
8012H linear memory unavailable
8013H physical memory unavailable
8014H backing store unavailable
8016H handle unavailable
8021H invalid value (BX:CX = 0)
8023H invalid handle (in SI:DI)
Notes:
o After this function returns, the previous handle for the
memory block is invalid and should not be used.
o When increasing the size of a block, this function always
creates committed pages. When decreasing the block size,
this call will correctly free all possible page types
(committed pages, uncommitted pages, and mapped pages).
The linear address and handle of the memory block may
change as a result of this call.
o It is the client's responsibility to update any
descriptors that map the memory block with the new linear
address after resizing the block.
o This function returns an error if the client attempts to
resize a memory block to zero bytes.
Int 31H Function 0504H [1.0]
Allocate Linear Memory Block
Allocates a block of page-aligned linear address space. The
base address of the block may be specified by the client,
and pages within the block may be committed or uncommitted.
Call With:
AX = 0504H
EBX = desired page-aligned linear address of memory
block,
or zero if linear address unspecified
ECX = size of block (bytes, must be nonzero)
EDX = flags
Bit Significance
0 0 = create uncommitted pages
1 = create committed pages
1-31 reserved, should be zero
Returns:
if function successful
Carry flag= clear
EBX = linear address of memory block
ESI = handle for memory block
if function unsuccessful
Carry flag= set
AX = error code
8001H unsupported function (16-bit host)
8012H linear memory unavailable
8013H physical memory unavailable
8014H backing store unavailable
8016H handle unavailable
8021H invalid value (ECX = 0)
8025H invalid linear address (EBX not page
aligned)
Notes:
o A DPMI 1.0 host that is 16-bit only will not support this
function.
o A 16-bit client of a 32-bit DPMI 1.0 host can use this
function.
o The allocated block is always page-aligned. If a
specific linear address is not requested (EBX = 0), the
DPMI host allocates the memory block at any available
page-aligned linear address. If a specific linear
address is requested (EBX nonzero), the host either
allocates the block at the specified address or returns
error code 8012H (linear memory unavailable).
o Int 31H Function 0501H, which can also be used to
allocate linear memory blocks, does not necessarily
page-align its blocks and does not have the ability to
create uncommitted pages or allocate a block at a
specific linear address.
Int 31H Function 0505H [1.0]
Resize Linear Memory Block
Changes the size of a memory block that was previously
allocated with the Allocate Linear Memory Block function
(Int 31H Function 0504H).
Call With:
AX = 0505H
ESI = memory block handle
ECX = new block size (bytes, must be nonzero)
EDX = flags
Bit Significance
0 0 = create uncommitted pages
1 = create committed pages
1 0 = do not update segment descriptors
1 = segment descriptor update required
2-31 reserved, must be zero
and, if bit 1 of EDX is set (1):
ES:EBX = selector:offset of a buffer containing an array
of selectors, 1 word (16 bits) per selector
EDI = count of selectors in array
Returns:
if function successful
Carry flag= clear
EBX = new linear base address of memory block
ESI = new handle for memory block
if function unsuccessful
Carry flag= set
AX = error code
8001H unsupported function (16-bit host)
8012H linear memory unavailable
8013H physical memory unavailable
8014H backing store unavailable
8016H handle unavailable
8021H invalid value (ECX=0)
8023H invalid handle (in ESI)
Notes:
o A DPMI 1.0 host that is 16-bit only will not support this
function.
o A 16-bit client of a 32-bit DPMI 1.0 host can use this
function.
o After this function returns, the previous handle for the
memory block is invalid and should not be used.
o If this function fails, the block's size and base address
are always unmodified.
o If the size of the block is increased, the new pages are
committed or uncommitted according to the value of bit 0
of EDX, and the block's linear base address may change.
If the size of the block is decreased, pages at the end
of the block are freed, and the block's base address is
always unchanged.
o If the block's linear base address is changed by this
function, and the function was called with bit 1 of EDX
set (1), the DPMI host updates the descriptors f
or each of the segments in the update list which fall within the
memory block. Descriptors for segments which do not fall
within the memory block are not modified. Expand-up
segments fall within the memory block if the segment base
is within the block. Expand-down segments fall within
the memory block if the (segment base + the limit - 1) is
within the block. In either case, the segment base is
modified by the distance the block moves, and the segment
limit is not changed. The moving of the memory block and
the updating of descriptors is performed atomically; i.e.
the host will not deliver any hardware interrupts to the
client during the update.
o Int 31H Function 0503H, which also resizes linear memory
blocks, does not necessarily page-align blocks and cannot
create uncommitted pages or update descriptors.
Int 31H Function 0506H [1.0]
Get Page Attributes
Returns the attributes of one or more pages within a linear
memory block previously allocated with Int 31H Function
0504H.
Call With:
AX = 0506H
ESI = memory block handle
EBX = base offset in memory block of page (or of first
page, if requesting attributes for multiple
pages)
ECX = number of pages
ES:EDX = selector:offset of a buffer to receive page
attributes, 1 word (16-bits) per page (see Note)
Returns:
if function successful
Carry flag= clear
and buffer at ES:EDX filled in with page attributes (see
Note)
if function unsuccessful
Carry flag= set
AX = error code
8001H unsupported function (16-bit host)
8023H invalid handle (in ESI)
8025H invalid linear address (Specified range
is not within specified block)
Notes:
o A DPMI 1.0 host that is 16-bit only will not support this
function.
o A 16-bit client of a 32-bit DPMI 1.0 host can use this
function.
o If EBX is not aligned, it will be rounded down to the
next lower page boundary.
o The specified buffer is filled in by the DPMI host with
the attributes of the requested pages, 1 word (16-bits)
per page, in the following format:
Bits Significance
0-2 page type (0-7)
Value Meaning
0 uncommitted page
1 committed page
2 mapped page
3-7 currently unused
3 0 = page is read-only
1 = page is read/write
4 0 = accessed/dirty bits not available for this
page
1 = accessed/dirty bits are supplied for this
page in bits 5-6
5 0 = page has not been accessed (if bit 4=1)
1 = page has been accessed (if bit 4=1)
6 0 = page has not been modified (if bit 4=1)
1 = page has been modified (if bit 4=1)
7-15 reserved, currently zero
o Mapped pages can only occur in memory blocks under DPMI
hosts that support the Device Mapping capability or the
Conventional Memory Mapping capability. See Int 31H
Functions 0401H, 0508H, and 0509H.
o The dirty and accessed bits are only supplied if the DPMI
host supports the Page Accessed/Dirty capability. DPMI
hosts that support this capability are required to return
dirty and accessed bits for all committed pages and for
mapped pages created with the Map Conventional Memory
call (Int 31H Function 0509H). However, dirty and
accessed bits may not be returned for individual mapped
pages created with the Map Device call (Int 31H Function
0508H) if the host is using page table entries (PTEs) to
virtualize the device.
Int 31H Function 0507H [1.0]
Set Page Attributes
Sets the attributes of one or more pages within a linear
memory block previously allocated with Int 31H Function
0504H. This function can be used to change a committed page
or a mapped page to an uncommitted page, change an
uncommitted page or a mapped page to a committed page, or
modify the read/write bit and optionally the accessed and
dirty bits on a committed or mapped page.
Call With:
AX = 0507H
ESI = memory block handle
EBX = offset within memory block of page(s) whose
attributes are to be modified
ECX = number of pages
ES:EDX = selector:offset of a buffer containing page
attributes, 1 word (16-bits) per page (see Note)
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8001H unsupported function (16-bit host)
8002H invalid state (page in wrong state for
request)
8013H physical memory unavailable
8014H backing store unavailable
8021H invalid value (illegal request in bits
0-2 of one or more page attribute words)
8023H invalid handle (in ESI)
8025H invalid linear address (specified range
is not within specified block)
ECX = number of pages that have been set
Notes:
o A DPMI 1.0 host that is 16-bit only will not support this
function.
o A 16-bit client of a 32-bit DPMI 1.0 host can use this
function.
o If EBX is not aligned, it will be rounded down to the
next lower page boundary.
o An uncommitted page can be created from:
a committed page, by releasing the physical memory or
backing store allocated to the page;
a mapped page, by marking it uncommitted; or
an uncommitted page, by doing nothing.
o A committed page can be created from:
an uncommitted page or mapped page, by allocating
physical memory or backing store (with undefined, or
zero-filled contents) for the page; or
a committed page, by doing nothing (page contents
unmodified).
o The attribute word (16-bits) specified for a page has the
following format (bits 3-6 are only relevant if page is
being created committed or its attributes are being
modified, i.e. the value in bits 0-2 of the page
attribute is 1 or 3):
Bits Significance
0-2 page type (0-7)
Value Meaning
0 create page uncommitted
1 create page committed
2 not allowed
3 modify attributes without changing page
type
4-7 not allowed
3 0 = page is read-only
1 = page is read/write
4 0 = don't modify accessed/dirty bits for page
1 = set accessed/dirty bits as specified in
bits 5-6
5 0 = mark page as not accessed (if bit 4=1)
1 = mark page as accessed (if bit 4=1)
6 0 = mark page as not dirty (if bit 4=1)
1 = mark page as dirty (if bit 4=1)
7-15 reserved, should be zero
o This function, and the optional Map Device and Map
Conventional Memory functions (Int 31H Functions 0508H
and 0509H), are the only means of changing the type of a
page within an existing memory block.
o The page read/write bit, and optionally the accessed and
dirty bits, can be modified on an existing committed or
mapped page, or on a committed page when it is initially
created from an uncommitted page or a mapped page.
However, the accessed and dirty bits are ignored if the
host does not support the Page Accessed/Dirty capability.
See Int 31H Function 0401H.
o Visible page faults (page faults that can be serviced by
a client-installed exception handler) can only occur for
uncommitted pages or read-only pages (for definitions of
transparent page fault and visible page fault, see
Appendix A: Glossary).
Int 31H Function 0508H [Optional] [1.0]
Map Device in Memory Block
Maps the physical addresses assigned to a device onto the
linear addresses of a memory block previously allocated with
Int 31H Function 0504H.
Call With:
AX = 0508H
ESI = memory block handle
EBX = offset within memory block of page(s) to be
mapped (must be page-aligned)
ECX = number of pages to map
EDX = physical address of device (must be
page-aligned)
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8001H unsupported function (Device Mapping
Capability not supported)
8003H system integrity (invalid device address)
8023H invalid handle (in ESI)
8025H invalid linear address (specified range
is not within specified block or EBX/EDX
is not page-aligned)
Notes:
o 16-bit DPMI hosts will not support this function. A
16-bit client of a 32-bit DPMI 1.0 host can use this
function.
o Support of this call by 32-bit DPMI hosts is optional.
Application programs or DOS Extenders which require this
call in order to run are not DPMI Compliant.
o Any committed or mapped pages resided in the linear
address range that is being mapped into will be
uncommitted or unmapped automatically by the host.
o All pages created by this call have the mapped bit (bit
2) set in the attributes returned by the Get Page
Attributes function (Int 31H Function 0506H).
o This functio
n differs from the Create Physical Address Mapping function (Int 31H
Function 0800H) in that this function supports mapping of
physical devices within an existing memory block, rather
than at an arbitrary linear address. Use of an existing
memory block gives 32-bit programs the ability to access
physical devices with NEAR pointers, which is often
highly desirable for performance reasons.
o Unlike Int 31H Function 0800H, this function allows
mapping of addresses below 1 MB that do not lie within
RAM available for use by programs; e.g. this function can
be used to map the refresh buffers of IBM-compatible
display adapters.
o If the DPMI host is not virtualizing the device, it must
disable any memory caching on the mapped pages; in
particular, on the 486 or later, the PCD (page cache
disable) bit must be set in the page table entries.
o DPMI hosts that do not virtualize physical devices can
support this function by creating page table entries that
map the physical device. The page table entries must be
marked as mapped so that the host knows not to attempt
freeing of physical memory for the pages when the memory
block is freed.
o DPMI hosts are allowed to support this function for some
physical devices and not for others, because mapping of
virtualized devices requires page aliasing in the host -
a complex task. DPMI hosts with partial support for this
function may fail the function call on virtualized
devices (such as displays), and allow the call on
non-virtualized devices (such as the Weitek
coprocessors). Allowing the client to map a physical
device so that it can be accessed with NEAR references,
for example, may help the client achieve considerably
better performance.
Int 31H Function 0509H [Optional] [1.0]
Map Conventional Memory in Memory Block
Aliases linear addresses below the 1 MB boundary onto the
linear addresses of a memory block previously allocated with
Int 31H Function 0504H.
Call With:
AX = 0509H
ESI = memory block handle
EBX = offset within memory block of page(s) to be
mapped (must be page-aligned)
ECX = number of pages to map
EDX = linear address of conventional memory (must be
page-aligned)
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8001H unsupported function (Conventional Memory
Mapping Capability not supported)
8003H system integrity (invalid conventional
memory address)
8023H invalid handle (in ESI)
8025H invalid linear address (specified range
is not within specified block, or EBX/EDX
is not page aligned)
Notes:
o 16-bit DPMI hosts will not support this function. A
16-bit client of a 32-bit DPMI 1.0 host can use this
function.
o Support of this call by 32-bit DPMI hosts is optional.
Application programs or DOS Extenders which require this
call in order to run are not DPMI Compliant.
o Any committed or mapped pages resided in the linear
address range that is being mapped into will be
uncommitted or unmapped automatically by the host.
o A client may only map conventional memory that it already
owns; i.e. memory which the client previously allocated
with Int 31H Function 0100H or by calling DOS's Int 21H
Function 48H directly via the translation services.
o All pages created by this call have the mapped bit (bit
2) set in the attributes returned by the Get Page
Attributes function (Int 31H Function 0506H).
o DPMI hosts that do not implement virtual memory can
support this function by simply copying page table
entries. The entries must be marked as mapped so that
the host knows not to free up those physical pages when
the memory block is freed.
o DPMI hosts that provide virtual memory must implement
some form of page aliasing in order to support this
function.
o The function can provide a large contiguous memory space
without virtual memory support.
Implementors of DPMI hosts which do not provide virtual
memory are encouraged to support this function. Without
this function, conventional memory may be inaccessible to
a 32-bit nonsegmented client, because the client may need
contiguous linear memory for its code and data. 32-bit
clients can always guarantee that conventional memory is
not wasted with the following strategy:
Call DOS to allocate any free conventional memory
If the DPMI host supports virtual memory, call the Mark
Real Mode Region Pageable function (Int 31H Function
0602H) to ensure that the host has not locked down
conventional memory.
If the host does not support virtual memory but supports
the Map Conventional Memory function (Int 31H Function
0509H), allocate a memory block with uncommitted pages,
then use Function 0509H to make the physical memory
allocated below 640 KB addressable in the memory block,
and therefore useable by the 32-bit application program.
Int 31H Function 050AH [1.0]
Get Memory Block Size and Base
Returns the size of a memory block that was previously
allocated with Int 31H Function 0501H or 0504H.
Call With:
AX = 050AH
SI:DI = memory block handle
Returns:
if function successful
Carry flag= clear
SI:DI = size of memory block (bytes)
BX:CX = base address of memory block if function
unsuccessful
Carry flag= set
AX = error code
8023H invalid handle
Int 31H Function 050BH [1.0]
Get Memory Information
Returns information about available physical and virtual
memory. Since DPMI clients will often run in multitasking
environments, some of information related to shared
resources returned by this function should only be
considered as advisory.
Call With:
AX = 050BH
ES:(E)DI= selector:offset of 128-byte buffer
Returns:
if function successful
Carry flag= clear (this function always succeeds in DPMI
1.0)
and the buffer pointed to by ES:(E)DI is filled in with
the following information:
Offset Length Contents
00H 4 Total allocated bytes of physical memory
controlled by DPMI host
04H 4 Total allocated bytes of virtual memory
controlled by DPMI host
08H 4 Total available bytes of virtual memory
controlled by DPMI host
0CH 4 Total allocated bytes of virtual memory
for this virtual machine
10H 4 Total available bytes of virtual memory
for this virtual machine
14H 4 Total allocated bytes of virtual memory
for this client
18H 4 Total available bytes of virtual memory
for this client
1CH 4 Total locked bytes of memory for this
client
20H 4 Maximum locked bytes of memory for this
client
24H 4 Highest linear address available to this
client
28H 4 Size in bytes of largest available free
memory block
2CH 4 Size of minimum allocation unit in bytes
30H 4 Size of the allocation alignment unit in
bytes
34H 4CH Reserved, currently zero
if function unsuccessful
Carry flag= set (this function always fails in DPMI 0.9)
Notes:
o DPMI 1.0 clients should use this function in preference
to Int 31H Function 0500H.
o The "total available bytes" field of the data structure
pointed by ES:(E)DI means the total bytes minus all of
the allocated bytes.
Int 31H Function 0600H [0.9]
Lock Linear Region
Locks the specified linear address range.
Call With:
AX = 0600H
BX:CX = starting linear address of memory to lock
SI:DI = size of region to lock (bytes)
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8013H physical memory unavailable
8017H lock count exceeded
8025H invalid linear address (unallocated
pages)
Notes:
o If the function returns an error, none of the memory has
been locked.
o If the specified region overlaps part of a page at the
beginning or end of the region, the page(s) will be
locked.
o This function may be called more than once for a given
page; the DPMI host maintains a lock count for each page.
o This function is ignored by DPMI implementations that do
not support virtual memory; the function will return the
Carry flag clear to indicate success, but has no other
effect. DPMI hosts which support virtual memory may also
choose to ignore this function, but such hosts must be
able to handle page faults transparently at arbitrary
points during a client's execution, including within
interrupt and exception handlers.
Int 31H Function 0601H [0.9]
Unlock Linear Region
Unlocks a linear address range that was previously locked
using the Lock Linear Region function (Int 31H Function
0600H).
Call With:
AX = 0601H
BX:CX = starting linear address of memory to unlock
SI:DI = size of region to unlock (bytes)
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8002H invalid state (page not locked)
8025H invalid linear address (unallocated
pages)
Notes:
o If the function returns an error, none of the memory has
been unlocked.
o If the specified region overlaps part of a page at the
beginning or end of the region, the page(s) will be
unlocked.
o A lock count is maintained for each locked page; the page
is not unlocked until the lock count is decremented to
zero (i.e. the number of Lock Region Int 31H Function
0600H calls has been balanced by the same number of
Unlock Region Int 31H Function 0601H calls).
o This function is ignored by DPMI implementations that do
not support virtual memory; the function will return the
Carry flag clear to indicate success, but has no other
effect. DPMI hosts which support virtual memory may also
choose to ignore this function, but such hosts must be
able to handle page faults transparently at arbitrary
points during a client's execution, including within
interrupt and exception handlers.
Int 31H Function 0602H [0.9]
Mark Real Mode Region as Pageable
Advises the DPMI host that the specified memory below the 1
MB boundary may be paged to disk.
Call With:
AX = 0602H
BX:CX = starting linear address of memory to mark as
pageable
SI:DI = size of region to be marked (bytes)
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8002H invalid state (region already marked as
pageable)
8025H invalid linear address (region is above 1
MB boundary)
Notes:
o If the function returns an error, none of the memory has
been marked as pageable.
o If the specified region overlaps part of a page at the
beginning or end of the region, the page(s) will not be
marked as pageable.
o Pageability information for a real mode region is
maintained as a binary state, not a count. Therefore,
multiple calls to this function for the same region have
no effect.
o For compatibility with DPMI version 0.9 hosts, a client
must call the Relock Real Mode Region function (Int 31H
Function 0603H) to relock the memory region before
terminating. Memory that remains unlocked after the
client has terminated could result in fatal page faults
when another program is executed in the same address
space. DPMI 1.0 hosts automatically relock real mode
memory at client termination.
o Under some DPMI hosts, all conventional memory may be
locked by default. If a protected mode program is using
memory in the first megabyte of address space, it is
recommended that this function be used to turn off
automatic page locking for regions of memory that will
not be touched at interrupt time.
o The client must not mark memory as pageable in regions
that it does not own; i.e. it may only mark as pageable
memory that it has previously allocated with Int 31H
Function 0100H or by a direct call to DOS via the
translation functions. For example, marking all free DOS
memory as pageable under some DPMI hosts could cause a
page fault to occur while inside of DOS, resulting in a
crash. Also, a client should not mark the DPMI host data
area as pageable.
o Note that address space marked as pageable by this
function can still be locked using the Lock Linear Region
function (Int 31H Function 0600H). This function is
just an advisory service to allow memory that does not
need to be locked to be paged out; it disables any
automatic locking of real mode memory performed by the
DPMI host.
o This function is ignored by DPMI implementations that do
not support virtual memory; the function will return the
Carry flag clear to indicate success, but has no other
effect. DPMI hosts which support virtual memory may also
choose to ignore this function, but such hosts must be
able to handle page faults transparently at arbitrary
points during a client's execution, including within
interrupt and exception handlers.
Int 31H Function 0603H [0.9]
Relock Real Mode Region
Relocks a memory region that was previously declared as
pageable with the Mark Real Mode Region as Pageable function
(Int 31H Function 0602H).
Call With:
AX = 0603H
BX:CX = starting linear address of memory to relock
SI:DI = size of region to relock (bytes)
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8002H invalid state (region not marked as
pageable)
8013H physical memory unavailable
8025H invalid linear address (region is above 1
MB boundary)
Notes:
o If the function returns an error, none of the memory has
been relocked.
o If the specified region overlaps part of a page at the
beginning or end of the region, the page(s) will not be
relocked.
o This function is ignored by DPMI implementations that do
not support virtual memory; the function will return the
Carry flag clear to indicate success, but has no other
effect. DPMI hosts which support virtual memory may also
choose to ignore this function, but such hosts must be
able to handle page faults transparently at arbitrary
points during a client's execution, including within
interrupt and exception handlers.
o If Function 0602H is implemented as a "no-operation" on a
particular DPMI host, this function will likewise do
nothing. In other words, this function should not be
used to lock memory, but only to restore the default
state of the host's conventional memory locking.
Int 31H Function 0604H [0.9]
Get Page Size
Returns the size of a single memory page in bytes.
Call With:
AX = 0604H
Returns:
if function successful
Carry flag= clear
BX:CX = page size in bytes
if function unsuccessful
Carry flag= set
AX = error code
8001H unsupported function (16-bit host)
Int 31H Function 0700H [0.9]
Reserved
Function 0700H is reserved for historical reasons and should
not be called.
Int 31H Function 0701H [0.9]
Reserved
Function 0701H is reserved for historical reasons and
should not be called.
Int 31H Function 0702H [0.9]
Mark Page as Demand Paging Candidate
Notifies the DPMI host that a range of pages may be placed
at the head of the page-out candidate list, forcing these
pages to be replaced ahead of other pages even if the memory
has been accessed recently. The contents of the pages will
be preserved.
Call With:
AX = 0702H
BX:CX = starting linear address of pages to mark as
paging candidates
SI:DI = size of region to mark (bytes)
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8025H invalid linear address (range
unallocated)
Notes:
o This function does not force the pages to be swapped to
disk immediately and should be treated as advisory only.
o This function will always succeed on hosts that do not
implement demand-paged virtual memory.
o Partial pages will not be marked.
o This function is useful, for example, if a client knows
that a given piece of data will not be accessed for a
long period of time. That data is ideal for swapping to
disk so that the physical memory it occupies can be used
for other purposes.
Int 31H Function 0703H [0.9]
Discard Page Contents
Discards the entire contents of a given linear memory range.
This function is used when a memory object (such as a data
structure) that occupies a given area of memory is no longer
needed, so that the area will not be paged to disk
unnecessarily. The contents of the discarded region will be
undefined.
Call With:
AX = 0703h
BX:CX = starting linear address of pages to discard
SI:DI = size of region to discard (bytes)
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8025H invalid linear address (range
unallocated)
Notes:
o Partial pages and locked pages will not be discarded.
Int 31H Function 0800H [0.9]
Physical Address Mapping
Converts a physical address into a linear address.
This function allows device drivers running under DPMI
hosts which use paging to reach physical memory that is
associated with their devices above the 1 MB boundary
Examples of such devices are the Weitek numeric coprocessor
(usually mapped at 3 GB), buffers that hold scanner bit
maps, and high-end displays that can be configured to make
display memory appear in extended memory.
Call With:
AX = 0800H
BX:CX = physical address of memory
SI:DI = size of region to map (bytes)
Returns:
if function successful
Carry flag= clear
BX:CX = linear address that can be used to access the
physical memory
if function unsuccessful
Carry flag= set
AX = error code
8003H system integrity (DPMI host memory
region)
8021H invalid value (address is below 1 MB
boundary)
Notes:
o It is the caller's responsibility to allocate and
initialize a descriptor for access to the memory.
o This function should only be used by clients that
absolutely require direct access to a memory mapped
device at physical addresses above 1 MB. Clients should
not use this function to access memory below the 1 MB
boundary (the real mode addressable region). See also
Int 31H Functions 0002H, 0508H, and 0509H.
o When this function is called, the DPMI host either
creates page table entries that directly map the physical
addresses requested and returns the linear address of the
created page table entries, or else just returns the
linear address of the memory region that is already used
to map the requested device. For example, if the client
attempts to map a Weitek coprocessor and the host already
has a linear region set up to map the Weitek chip and
virtualize it, it would simply return the linear address
of the existing region. If the host does not virtualize
the Weitek chip, it would create 16 page table entries
that map the 64 KB Weitek address space and return a
linear address corresponding to the new page table
entries.
o If the host is not virtualizing the device, it must
disable any memory caching on the mapped pages; in
particular, on the 80486 the host must set the PCD (page
cache disable) bit in the page table entries.
o The host is permitted to fail any memory mapping call.
However, the host should support this function whenever
possible, to achieve compatibility with application
programs that use memory-mapped devices of which the host
is not aware. Useful guidelines are that the host should
fail any attempt to map addresses below 1 MB, or
addresses which the host considers to be general-purpose
RAM memory. Attempts to map any other physical address
should succeed, since the host should either (a) already
know about the device and be able to return a linear
address used to access the device, or (b) assume the
program is attempting to map a legitimate device of which
the host has no knowledge.
o Programs and device drivers which need to perform DMA I/O
to physical addresses in a virtualized hardware
environment should use the Virtual DMA Services (see the
Glossary entry for the Virtual DMA Services
Specification). Also see page 10 of the DPMI execution
environment section.
Int 31H Function 0801H [1.0]
Free Physical Address Mapping
Releases a mapping of physical to linear addresses that was
previously obtained with the Physical Address Mapping
function (Int 31H Function 0800H).
Call With:
AX = 0801H
BX:CX = linear address returned by physical address
mapping call
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8025H invalid linear address
Notes:
o The client should call this function when it is finished
using a device previously mapped to linear addresses with
the Physical Address Mapping function (Int 31H Function
0800H).
Int 31H Function 0900H [0.9]
Get and Disable Virtual Interrupt State
Disables the virtual interrupt flag and returns the previous
state of the virtual interrupt flag.
Call With:
AX = 0900H
Returns:
Virtual interrupts disabled
Carry flag= clear (this function always succeeds)
AL = 0 if virtual interrupts were previously disabled
= 1 if virtual interrupts were previously enabled
Notes:
o AH is not changed by this function. Therefore, the
previous state can be restored by simply executing
another Int 31H. See Int 31H Function 0901H.
o A client that does not need to know the prior interrupt
state can execute the CLI instruction rather than calling
this function. The instruction may be trapped by the
host and should be assumed to be very slow.
Int 31H Function 0901H [0.9]
Get and Enable Virtual Interrupt State
Enables the virtual interrupt flag and returns the previous
state of the virtual interrupt flag.
Call With:
AX = 0901H
Returns:
Virtual interrupts enabled
Carry flag= clear (this function always succeeds)
AL = 0 if virtual interrupts were previously disabled
= 1 if virtual interrupts were previously enabled
Notes:
o AH is not changed by this function. Therefore, the
previous state can be restored by simply executing
another Int 31H. See Int 31H Function 0900H.
o A client that does not need to know the prior interrupt
state can execute the STI instruction rather than calling
this function. The instruction may be trapped by the
host and should be assumed to be very slow.
Int 31H Function 0902H [0.9]
Get Virtual Interrupt State
Returns the current state of the virtual interrupt flag.
Call With:
AX = 0902H
Returns:
Carry flag= clear (this function always succeeds)
AL = 0 if virtual interrupts are disabled
= 1 if virtual interrupts are enabled
Notes:
o This function should be used in preference to the PUSHF
instruction to examine the interrupt flag, because the
PUSHF instruction returns the physical interrupt flag
rather than the virtualized (per-client) interrupt flag.
On some DPMI hosts, the physical interrupt flag will
always be enabled, even when hardware interrupts are not
being passed through to the client.
Int 31H Function 0A00H [0.9]
Get Vendor-Specific API Entry Point
Returns an address which can be called to use host-specific
extensions to the standard set of DPMI functions. DPMI 1.0
clients should avoid use of this function (see Note).
Call With:
AX = 0A00H
DS:(E)SI= selector:offset of ASCIIZ (null-terminated)
string which identifies the DPMI host vendor
Returns:
if function successful
Carry flag= clear
ES:(E)DI= selector:offset of extended API entry point
and DS, FS, GS, EAX, EBX, ECX, EDX, ESI, and EBP may be
modified.
if function unsuccessful
Carry flag= set
AX = error code
8001H unsupported function (extension not
found)
Notes:
o The null-terminated string specifies the host-specific
vendor name or some other unique identifier to obtain a
specific extension entry point. The string comparison
used to look up the API entry point is case-sensitive.
o Clients must use a FAR CALL to reach the extended API
entry point.
o All extended API parameters are specified by the vendor.
o DPMI 1.0 clients should use Int 2FH Function 168AH in
preference to this function. DPMI 1.0 hosts support this
function solely for backward compatibility with DPMI 0.9
clients.
Int 31H Function 0B00H [0.9]
Set Debug Watchpoint
Sets a debug watchpoint at the specified linear address.
Call With:
AX = 0B00H
BX:CX = linear address of watchpoint
DL = size of watchpoint (1, 2, or 4 bytes)
DH = type of watchpoint
0 = execute
1 = write
2 = read/write
Returns:
if function successful
Carry flag= clear
BX = watchpoint handle
if function unsuccessful
Carry flag= set
AX = error code
8016H too many breakpoints
8021H invalid value (in DL or DH)
8025H invalid linear address (linear address
not mapped or alignment error)
Notes:
o Under DPMI 1.0, the handle will be in the range 0-14.
Under DPMI 0.9, the handle range is not limited.
o The watchpoint handle corresponds to the bit number in
the Virtual DR6 returned in the exception frame (see Int
31H Function 0212H and page 18).
Int 31H Function 0B01H [0.9]
Clear Debug Watchpoint
Clears a debug watchpoint that was previously set using the
Set Debug Watchpoint function (Int 31H Function 0B00H), and
releases the watchpoint
handle.
Call With:
AX = 0B01H
BX = watchpoint handle
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8023H invalid handle
Int 31H Function 0B02H [0.9]
Get State of Debug Watchpoint
Returns the state of a debug watchpoint that was previously
set using the Set Debug Watchpoint function (Int 31H
Function 0B00H).
Call With:
AX = 0B02H
BX = watchpoint handle
Returns:
if function successful
Carry flag= clear
AX = watchpoint status
Bit Significance
0 0 = watchpoint has not been encountered
1 = watchpoint has been encountered
1-15 reserved
if function unsuccessful
Carry flag= set
AX = error code
8023H invalid handle
Notes:
o The client can use Int 31H Function 0B03H to clear the
watchpoint state without releasing the watchpoint handle.
Int 31H Function 0B03H [0.9]
Reset Debug Watchpoint
Resets the state of a previously defined debug watchpoint;
i.e. a subsequent call to Int 31H Function 0B02H will
indicate that the debug watchpoint has not been encountered.
Call With:
AX = 0B03H
BX = watchpoint handle
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8023H invalid handle
Int 31H Function 0C00H [1.0]
Install Resident Service Provider Callback
Protected mode resident service providers (protected mode
TSRs) can provide services to 16-bit DPMI programs, 32-bit
DPMI programs, or both. A resident service provider uses
this function to request notification from the host whenever
another DPMI program in the same virtual machine is loaded
or terminated.
Call With:
AX = 0C00H
ES:(E)DI= selector:offset of 40-byte buffer with the
following structure:
OffsetLengthContents
00H 8Descriptor for 16-bit data segment
08H 8Descriptor for 16-bit code segment
10H 2Offset of 16-bit callback procedure
12H 2Reserved
14H 8Descriptor for 32-bit data segment
1CH 8Descriptor for 32-bit code segment
24H 4Offset of 32-bit callback procedure
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8021H invalid value (access rights/type bytes
invalid, or offset outside segment
limits)
8025H invalid linear address (descriptor
references a linear address range outside
that allowed for DPMI clients)
8015H callback unavailable (host unable to
allocate resources for resident handler
initialization callback)
Notes:
o A DPMI client that uses this function declares its intent
to provide resident protected mode services. The client
must subsequently terminate and stay resident using Int
31H Function 0C01H. DPMI clients which intend to stay
resident only to provide services to real mode programs
should not use this function.
o The data structure provides room for a data descriptor, a
code descriptor, and an offset for both 16-bit and 32-bit
protected modes. The client can conveniently initialize
the descriptor fields to valid values by fetching copies
of its current code and data descriptors with Int 31H
Function 000BH.
o If only one mode is supported by the resident service
provider, then the code descriptor for the unsupported
mode should be initialized to zero.
o This function is called on the locked protected mode
stack.
o For further details on programming of resident service
providers, see page 41.
Int 31H Function 0C01H [1.0]
Terminate and Stay Resident
A resident service provider uses this function after its
initialization to terminate execution while leaving its
protected mode memory (and optionally some real mode memory)
allocated.
Call With:
AX = 0C01H
BL = return code
DX = number of paragraphs (16-byte blocks) of DOS
memory to reserve
Returns:
Nothing (this call never returns)
Notes:
o This function should only be used by DPMI clients which
only provide resident services to other DPMI protected
mode clients. If the objective is only to provide
resident services to real mode programs, the client
should use the DPMI translation service Int 31H Function
0300H to invoke DOS's Int 21H Function 31H directly.
o The value in DX only specifies the size of DOS allocated
memory to reserve. Any protected mode memory owned by
the program remains allocated unless it is explicitly
released before executing this function. Note that the
value in DX must either be 0 or a minimum of 6. If DX is
0, the DPMI host executes a DOS real mode terminate
function (Int 21H Function 4CH), and no real mode memory
is reserved. If DX is nonzero, the DPMI host requests
the DOS real mode terminate-and-stay-resident function
(Int 21H Function 31H).
o If the client has not made a prior call to Int 31H
Function 0C00H, the client will simply be terminated.
o For further details on programming of resident service
providers, see page 41.
Int 31H Function 0D00H [1.0]
Allocate Shared Memory
Allocates a memory block that may be shared by DPMI clients.
Call With:
AX = 0D00H
ES:(E)DI= selector:offset of shared memory allocation
request structure in the following format:
Offset Length Contents
00H 4 Requested length of shared
memory block (set by client, may
be zero)
04H 4 Length actually allocated (set
by host)
08H 4 Shared memory handle (set by
host)
0CH 4 Linear address of shared memory
block (set by host)
10H 6 offset32:selector of ASCIIZ
(null-terminated ASCII) name for
shared memory block (set by
client)
16H 2 Reserved
18H 4 Reserved, must be zero
Returns:
if function successful
Carry flag= clear
and the request structure fields at offsets 04H, 08H, and
0CH updated by host
if function unsuccessful
Carry flag= set
AX = error code
8012H linear memory unavailable
8013H physical memory unavailable
8014H backing store unavailable
8016H handle unavailable
8021H invalid value (name for the memory block
is too long)
and the request structure fields at offsets 04H, 08H and
0CH unmodified by host
Notes:
o For 16-bit programs, the high word of the offset32 for
the ASCIIZ name must be zero.
o The maximum length of the shared memory block name is 128
characters, including the terminal null character.
o The linear address provided by the host is guaranteed to
be the same for all clients in all virtual machines using
a shared memory block. The client must establish
addressability for the block by allocating and
initializing a descriptor with separate function calls.
o No assumptions should be made about handle values.
Successive allocations of the same shared memory block by
the same client may return distinct handles; the client
is responsible for tracking and individually deallocating
each handle.
o The first client that allocates a shared memory block
determines its size; the length requested and the length
actually allocated will always be equal, if the
allocation succeeds at all. Subsequent allocations by
the same or different clients that specify the same or a
different size will succeed, but the size of the block
will remain unchanged. The actual size of the block is
always returned to the client at offset 4 in the shared
memory allocation request structure.
o Allocation of zero-length shared memory blocks is
explicitly allowed. The handle of a zero-length block
can be used with the serialization functions (Int 31H
Functions 0D02H and 0D03H) as a semaphore for
inter-client communication. The linear address that is
returned at offset 0CH in the data structure for
zero-length blocks is undefined, and any reference to it
may produce a page fault.
o The first paragraph (16 bytes) of the shared memory block
(or the entire shared block, if smaller than 16 bytes)
will always be initialized to zero on the first
allocation and can be used by clients as an "area
initialized" indicator. For example, a shared memory
block might be used by a suite of cooperating client
programs to hold a table of static data or a subroutine
library. The first client to allocate the shared memory
block can obtain exclusive ownership of the block with
Int 31H Function 0D02H, load the necessary data or code
into the block from disk, set the first 16 bytes of the
block to a nonzero value, and finally release its
ownership
of the block with Int 31H Function 0D03H. Other clients that allocate
the shared memory block can check the "area initialized"
indicator and know that the desired code or data is
already present in memory.
o Shared memory block allocations and serializations are
tracked by the host on a per client basis. All shared
memory allocations for a client are freed by the host
when the client terminates.
Int 31H Function 0D01H [1.0]
Free Shared Memory
Deallocates a shared memory block.
Call With:
AX = 0D01H
SI:DI = handle of shared memory block to free
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8023H invalid handle
Notes:
o The shared memory handle becomes invalid after the shared
memory block is deallocated, and should not be used in
any other function call (such as serialization).
o The host maintains virtual machine use counts and a
global use count for each shared memory block. A
virtual machine use count is the number of allocation
calls (Int 31H Function 0D00H) that have been issued by a
particular virtual machine for the shared block, while
the global use count corresponds to the number of virtual
machines which have access to the block. When a virtual
machine use count reaches zero, the clients in that
virtual machine no longer have addressability to the
shared memory block; when the global use count reaches
zero, the shared memory block is destroyed by the host.
o It is the client's responsibility to free any descriptors
that it has allocated to map the shared memory block.
o Applications should not depend on this function to
release a previous successful serialization for the same
shared memory block. Serialization is only released by
this function when the virtual machine use count goes to
0 (i.e., the client no longer has access to the shared
memory block).
Int 31H Function 0D02H [1.0]
Serialize on Shared Memory
Requests serialization of a shared memory block. Successful
serialization symbolizes ownership or right of access to a
block, and can be used by DPMI clients to synchronize the
inspection or modification of a shared memory block.
Call With:
AX = 0D02H
SI:DI = shared memory block handle
DX = option flags
Bit Significance
0 0 = suspend client until serialization
available
1 = return immediately with error if
serialization not available
1 0 = exclusive serialization requested
1 = shared serialization requested
2-15 reserved, must be zero
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8004H deadlock (host detected a deadlock
situation)
8005H request cancelled with Int 31H Function
0D03H
8017H lock count exceeded
8018H exclusive serialization already owned by
another client
8019H shared serialization already owned by
another client
8023H invalid handle
Notes:
o For each client, the DPMI host maintains four different
local (virtual machine) serialization counts (exclusive,
shared, pending shared, and pending exclusive) for each
shared memory block, as well as a global serialization
count. The global serialization count is only updated
when the sum of a virtual machine's exclusive and shared
serialization counts goes from 0 to 1 (serialize) or 1 to
0 (free).
o A successful exclusive serialization blocks any
serialization request (exclusive or shared) for the same
block by another virtual machine. Exclusive
serialization should be regarded as "ownership for
writing," and should only be requested if the client
intends to modify the block. A successful shared
serialization will only block requests for exclusive
serialization by another client. Shared serialization
can be thought of as "read-only access," and should used
when the client only intends to inspect the block and
will not change its contents.
o Setting bit 0 of DX to 1 when the serialization request
is made allows a client to determine whether a shared
memory area is serialized without being suspended.
Clients which "poll" for the availability of a resource
in this manner are encouraged to yield the CPU with Int
2FH Function 1680H at appropriate intervals.
o A serialization call that causes a client to be suspended
can be canceled by a client interrupt service routine
(such as a keyboard or timer interrupt handler)
requesting the Free Serialization function (Int 31H
Function 0D03H). In such cases, the original
serialization request will return with the Carry flag set
and AX = 8005H.
o A client that has been suspended while waiting for
serialization of a shared memory block can still service
interrupts. Some hosts may need to reissue the
serialization request on behalf of the client after the
interrupt service routine returns, but this event will be
invisible to the client.
o Hosts are not required to detect deadlock. Clients that
terminate and stay resident in order to function as
resident service providers, executing in the context of
other clients, must be careful to avoid deadlocks and
incorrect sequencing in acquiring and releasing
resources.
Int 31H Function 0D03H [1.0]
Free Serialization on Shared Memory
Releases a shared memory block serialization that was
previously obtained with Int 31H Function 0D02H.
Call With:
AX = 0D03H
SI:DI = shared memory block handle
DX = option flags
Bit Significance
0 0 = release exclusive serialization
1 = release shared serialization
1 0 = don't free pending serialization
1 = free pending serialization (see Note)
2-15 reserved, must be zero
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8002H invalid state (client does not own a
successful serialization of the specified
type)
8023H invalid handle
Notes:
o For each client, the DPMI host maintains four different
local (virtual machine) serialization counts (exclusive,
shared, pending shared, and pending exclusive) for each
shared memory block, as well as a global serialization
count. The global serialization count is only updated
when the sum of a virtual machine's exclusive and shared
serialization counts goes from 0 to 1 (serialize) or 1 to
0 (free).
o A client's interrupt handler can call this function with
bit 1 of DX set to cancel a serialization request that
has suspended the main thread of execution of the same
client. In such cases, the original serialization
request will return with the Carry flag set and AX =
8005H.
Int 31H Function 0E00H [1.0]
Get Coprocessor Status
Returns information about whether or not a numeric
coprocessor exists, the type of coprocessor available (if
any), and whether or not the host or client is providing
coprocessor emulation.
Call With:
AX = 0E00H
Returns:
if function successful
Carry flag= clear (this function always succeeds in DPMI
1.0)
AX = coprocessor status
Bit Significance
0 MPv (MP bit in the virtual MSW/CR0)
0 = numeric coprocessor is disabled for
this client
1 = numeric coprocessor is enabled for
this client
1 EMv (EM bit in the virtual MSW/CR0)
0 = client is not emulating coprocessor
instructions
1 = client is emulating coprocessor
instructions
2 MPr (MP bit from the actual MSW/CR0)
0 = numeric coprocessor is not present
1 = numeric coprocessor is present
3 EMr (EM bit from the actual MSW/CR0)
0 = host is not emulating coprocessor
instructions
1 = host is emulating coprocessor
instructions
4-7 coprocessor type
00H = no coprocessor
02H = 80287
03H = 80387
04H = 80486 with numeric coprocessor
05H-0FH reserved for future
numeric processors
8-15 not applicable
if function unsuccessful
Carry flag= set (this function always fails in DPMI 0.9)
Notes:
o If the real EM (EMr) bit is set, the host is supplying or
is capable of supplying floating point emulation.
o If the MPv bit is not set, the host may not need to save
the coprocessor state for this virtual machine to improve
system performance.
o MPr bit setting should be consistent with the setting of
coprocessor type information. Ignore MPr bit information
if it is in conflict with the coprocessor type
information.
o If the virtual EM (EMv) bit i
s set, the host delivers all coprocessor exceptions to the client, and
the client is performing its own floating point emulation
(whether or not a coprocessor is present or the host also
has a floating point emulator). In other words, if the
EMv bit is set, the host sets the EM bit in the real CR0
while the virtual machine is active, and reflects
coprocessor not present faults (Int 7) to the virtual
machine.
o A client can determine the CPU type with Int 31H Function
0400H, but a client should not draw any conclusions about
the presence or absence of a coprocessor based on the CPU
type alone.
Int 31H Function 0E01H [1.0]
Set Coprocessor Emulation
Enables or disables the numeric coprocessor for this virtual
machine and the reflection of coprocessor exceptions to the
client.
Call With:
AX = 0E01H
BX = coprocessor bits
Bit Significance
0 new value of MPv bit for client's virtual
CR0
0 = disable numeric coprocessor for this
client
1 = enable numeric coprocessor for this
client
1 new value of EMv bit for client's virtual
CR0
0 = client will not supply coprocessor
emulation
1 = client will supply coprocessor
emulation
2-15 not applicable
Returns:
if function successful
Carry flag= clear
if function unsuccessful
Carry flag= set
AX = error code
8026H invalid request (client requested
disabling coprocessor on a processor
which does not support this)
Notes:
o If the MPv bit is not set, the host may not need to save
the coprocessor state for this virtual machine to improve
system performance.
o If the virtual EM (EMv) bit is set, the host delivers all
coprocessor exceptions to the client, so that the client
can provide its own floating point emulation (whether or
not a coprocessor is present or the host also has a
floating point emulator). In other words, if the EMv bit
is set, the host sets the EM bit in the real CR0 while
the client is active, and reflects coprocessor not
present faults (Int 7) to the client.
o Floating point emulation can be tested on a system with a
numeric coprocessor by using this function to enable
client handling of coprocessor exceptions and disable the
coprocessor.
o The client should use Int 31H Function 0212H to register
an exception handler for coprocessor not present faults
(Int 7) prior to setting the EMv bit with this function.
o A client can determine the CPU type with Int 31H Function
0400H, and the presence or absence of a coprocessor with
Int 31H Function 0E00H. The client should not draw any
conclusions about the presence or absence of a
coprocessor based on the CPU type alone.
Appendix B: Error Codes and Messages
Nearly all Int 31H function calls can fail, either because
of client errors, unavailable resources, or internal host
problems. Most failures due to client errors and all
failures due to unavailable resources are reported to the
client via error codes. Some client errors, such as passing
an invalid pointer in a function call, may cause the host to
fault; the client can detect these events by installing an
exception handler.
Internal host errors are handled in a host-specific manner
and generally not reported to clients with an error code.
The only exception to this is the case when a host cannot
allocate internal resources. Any Int 31H function is capable
of returning error code 8010H to indicate this condition.
A DPMI 1.0 host signals an error by returning from a
function with the Carry flag set and an error code in AX.
If the error code has bit 15 clear (0), the DPMI host is
passing a DOS error code through to the client; for a list
of these error codes, consult a DOS technical reference. If
the error code has bit 15 set (1), it is generated within
the DPMI host, and is interpreted according to the list
below. All DPMI 1.0 hosts are required to check for the
error conditions listed in this specification, and must
return the error codes that are documented for each
function.
If Int 31H is invoked with an function number that is not
defined in this specification, the DPMI host will return the
"Unsupported Function" error code 8001H. The table lists all
defined error codes and their messages. Unused error codes
are reserved for the later versions of the DPMI
spcifications.
Err
or
Cod
e Name Explanation 800
1H Unsupported
function Returned in response to
any function call which is
not implemented by this
host, because the
requested function is
either undefined or
optional. 800
2H Invalid state Some object is in the
wrong state for the
requested operation. 800
3H System integrity The requested operation
would endanger system
integrity, e.g., a request
to map linear addresses
onto system code or data. 800
4H Deadlock Host detected a deadlock
situation. 800
5H Request
cancelled A pending serialization
request was cancelled. 801
0H Resource
Unavailable The DPMI host cannot
allocate internal
resources to complete an
operation. 801
1H Descriptor
unavailable Host is unable to allocate
a descriptor. 801
2H Linear memory
unavailable Host is unable to allocate
the required linear
memory. 801
3H Physical memory
unavailable Host is unable to allocate
the required physical
memory. 801
4H Backing store
unavailable Host is unable to allocate
the required backing
store. 801
5H Callback
unavailable Host is unable to allocate
the required callback
address. 801
6H Handle
unavailable Host is unable to allocate
the required handle. 801
7H Lock count
exceeded A locking operation
exceeds the maximum count
maintained by the host. 801
8H Resource owned
exclusively A request for
serialization of a shared
memory block could not be
satisfied because it is
already serialized
exclusively by another
client. 801
9H Resource owned
shared A request for exclusive
serialization of a shared
memory block could not be
satisfied because it is
already serialized shared
by another client. 802
1H Invalid value A numeric or flag
parameter has an invalid
value. 802
2H Invalid selector A selector does not
correspond to a valid
descriptor. 802
3H Invalid handle A handle parameter is
invalid. 802
4H Invalid callback A callback parameter is
invalid. 802
5H Invalid linear
address A linear address range
(either supplied as a
parameter or implied by
the call) is invalid. 802
6H Invalid request The request is not
supported by the
underlying hardware.
