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.