int31.gml

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

.* (c) Portions Copyright 1990, 1995 by Tenberry Software, Inc.
.*
.chap *refid=int31 Interrupt 31H DPMI Functions
.*
.np
.ix 'DPMI host' 'Windows 3.1'
.ix 'DPMI host' 'OS/2 VDM'
.ix 'DPMI host' '386Max'
.ix 'DPMI host' 'QEMM QDPMI'
When a &dos4g application runs under a DPMI host, such as Windows 3.1
in enhanced mode, an OS/2 virtual DOS machine, 386Max (with
DEBUG=DPMIXCOPY), or QEMM/QDPMI (with EXTCHKOFF), the DPMI host
provides the DPMI services, not &dos4g..
The DPMI host also provides virtual memory, if any.
Performance (speed and memory use) under different DPMI hosts varies
greatly due to the quality of the DPMI implementation.
.np
.ix 'INT 31H'
DPMI services are accessed using Interrupt 31H.
.np
The following describes the services provided by &dos4g and
&dos4gprd Professional in the absence of a DPMI host.
&dos4g supports many of the common DPMI system services.
Not all of the services described below are supported by other DPMI
hosts.
.np
.ix 'DPMI'
.ix 'DOS Protected-Mode Interface'
Some of the information in this chapter was obtained from the the DOS
Protected-Mode Interface (DPMI) specification.
It is no longer in print; however the DPMI 1.0 specification can be
obtained from the Intel ftp site.
Here is the URL.
.code begin
ftp://ftp.intel.com/pub/IAL/software_specs/dpmiv1.zip
.code end
.np
This ZIP file contains a Postscript version of the DPMI 1.0
specification.
.*
.section Using Interrupt 31H Function Calls
.*
.np
.ix 'DPMI'
.ix 'DOS Protected-Mode Interface'
Interrupt 31H DPMI function calls can be used only by protected-mode
programs.
.* Real-mode programs must use the equivalent Interrupt 21 calls
.* described in the chapter, "Interrupt 21H Functions".
.np
The general ground rules for Interrupt 31H calls are as follows:
.begbull
.bull
All Interrupt 31H calls modify the AX register.
Unsupported or unsuccessful calls return an error code in AX.
Other registers are saved unless they contain specified return values.
.bull
All Interrupt 31H calls modify flags:
Unsupported or unsuccessful calls return with the carry flag set.
Successful calls clear the carry flag.
Only memory management and interrupt flag management calls modify the
interrupt flag.
.bull
Memory management calls can enable interrupts.
.bull
All calls are reentrant.
.endbull
.np
The flag and register information for each call is listed in the
following descriptions of supported Interrupt 31H function calls.
.*
.section Int31H Function Calls
.*
.np
.ix 'DPMI' 'function calls'
.ix 'int 31H function calls'
The Interrupt 31H subfunction calls supported by &dos4g are listed
below by category:
.begbull
.bull
Local Descriptor Table (LDT) management services
.bull
DOS memory management services
.bull
Interrupt services
.bull
Translation services
.bull
DPMI version
.bull
Memory management services
.bull
Page locking services
.bull
Demand paging performance tuning services
.bull
Physical address mapping
.bull
Virtual interrupt state functions
.bull
Vendor specific extensions
.bull
Coprocessor status
.endbull
.np
Only the most commonly used Interrupt 31H function calls are supported
in this version.
.*
.beglevel
.*
.section Local Descriptor Table (LDT) Management Services
.*
.begnote
.*
.note Function 0000H
.*
.ix 'local descriptor table'
.ix 'LDT'
This function allocates a specified number of descriptors from the LDT
and returns the base selector.
Pass the following information:
.begpoint $compact
.point AX = 0000H
.point CX = number of descriptors to be allocated
.endpoint
.np
If the call succeeds, the carry flag is clear and the base selector is
returned in AX.
If the call fails, the carry flag is set.
.np
An allocated descriptor is set to the present data type, with a base
and limit of zero.
The privilege level of an allocated descriptor is set to match the
code segment privilege level of the application.
To find out the privilege level of a descriptor, use the
.mono lar
instruction.
.np
Allocated descriptors must be filled in by the application.
If more than one descriptor is allocated, the returned selector is the
first of a contiguous array.
Use Function 0003H to get the increment for the next selector in the
array.
.*
.note Function 0001H
.*
This function frees the descriptor specified.
Pass the following information:
.begpoint $compact
.point AX = 0001H
.point BX = the selector to free
.endpoint
.np
Use the selector returned with function 0000h when the descriptor was
allocated.
To free an array of descriptors, call this function for each
descriptor.
Use Function 0003H to find out the increment for each descriptor in
the array.
.np
If the call succeeds, the carry flag is clear; if it fails, the carry
flag is set.
.np
You can use this function to free the descriptors allocated for the
program's initial CS, DS, and SS segments, but you should not free
other segments that were not allocated with Function 0000H or Function
000DH.
.*
.note Function 0002H
.*
This function converts a real-mode segment to a descriptor that a
protected-mode program can address.
Pass the following information:
.begpoint $compact
.point AX = 0002H
.point BX = real-mode segment address
.endpoint
.np
If the call succeeds, it clears the carry flag and returns the
selector mapped to the real-mode segment in AX.
If the call fails, the carry flag is set.
.np
If you call this function more than once with the same real-mode
segment address, you get the same selector value each time.
The descriptor limit is set to 64KB.
.np
The purpose of this function is to give protected-mode programs easy
access to commonly used real-mode segments.
However, because you cannot modify or free descriptors created by this
function, it should be used infrequently.
Do not use this function to get descriptors for private data areas.
.np
To examine real-mode addresses using the same selector, first allocate
a descriptor, and then use Function 0007H to change the linear base
address.
.*
.note Function 0003H
.*
This function returns the increment value for the next selector.
Use this function to get the value you add to the base address of an
allocated array of descriptors to get the next selector address.
Pass the following information:
.begpoint $compact
.point AX = 0003H
.endpoint
.np
This call always succeeds.
The increment value is returned in AX.
This value is always a power of two, but no other assumptions can be
made.
.*
.note Function 0006H
.*
This function gets the linear base address of a selector.
Pass the following information:
.begpoint $compact
.point AX = 0006H
.point BX = selector
.endpoint
.np
If the call succeeds, the carry flag is clear and CX:DX contains the
32-bit linear base address of the segment.
If the call fails, it sets the carry flag.
.np
If the selector you specify in BX is invalid, the call fails.
.*
.note Function 0007H
.*
This function changes the base address of a specified selector.
Only descriptors allocated through Function 0000H should be modified.
Pass the following information:
.begpoint $compact
.point AX = 0007H
.point BX = selector
.point CX:DX = the new 32-bit linear base address for the segment
.endpoint
.np
If the call succeeds, the carry flag is clear; if unsuccessful, the
carry flag is set.
.np
If the selector you specify in BX is invalid, the call fails.
.*
.note Function 0008H
.*
This function sets the upper limit of a specified segment.
Use this function to modify descriptors allocated with Function 0000H
only.
Pass the following information:
.begpoint $compact
.point AX = 0008H
.point BX = selector
.point CX:DX = 32-bit segment limit
.endpoint
.np
If the call succeeds, the carry flag is clear; if unsuccessful, the
carry flag is set.
.np
The call fails if the specified selector is invalid, or if the
specified limit cannot be set.
.np
Segment limits greater than 1MB must be page-aligned.
This means that limits greater than 1MB must have the low 12 bits set.
.np
To get the limit of a segment, use the 32-bit form of
.mono lsl
for segment limits greater than 64KB.
.*
.note Function 0009H
.*
This function sets the descriptor access rights.
Use this function to modify descriptors allocated with Function 0000H
only.
To examine the access rights of a descriptor, use the
.mono lar
instruction.
Pass the following information:
.begpoint $compact
.point AX = 0009H
.point BX = selector
.point CL = Access rights/type byte
.point CH = 386 extended access rights/type byte
.endpoint
.np
If the call succeeds, the carry flag is clear; if unsuccessful, the
carry flag is set.
If the selector you specify in BX is invalid, the call fails.
The call also fails if the access rights/type byte does not match the
format and meet the requirements shown in the figures below.
.cp 30
.np
The access rights/type byte passed in CL has the format shown in the
figure below.
:cmt. :image xoff='0.0i' depth='4.0i' file='RSI\MEM3' text='Access Rights/Type'.
.figure *depth='4.0' *scale=100 *file='MEM3' Access Rights/Type
.cp 30
.np
The extended access rights/type byte passed in CH has the following
format.
:cmt. :image xoff='0.0i' depth='4.0i' file='RSI\MEM4' text='Extended Access Rights/Type'.
.figure *depth='4.0' *scale=100 *file='MEM4' Extended Access Rights/Type
.*
.note Function 000AH
.*
This function creates an alias to a code segment.
This function creates a data descriptor that has the same base and
limit as the specified code segment descriptor.
Pass the following information:
.begpoint $compact
.point AX = 000AH
.point BX = code segment selector
.endpoint
.np
If the call succeeds, the carry flag is clear and the new data
selector is returned in AX.
If the call fails, the carry flag is set.
The call fails if the selector passed in BX is not a valid code
segment.
.np
To deallocate an alias to a code segment, use Function 0001H.
.np
After the alias is created, it does not change if the code segment
descriptor changes.
For example, if the base or limit of the code segment change later,
the alias descriptor stays the same.
.*
.note Function 000BH
.*
This function copies the descriptor table entry for a specified
descriptor.
The copy is written into an 8-byte buffer.
Pass the following information:
.begpoint $compact
.point AX = 000BH
.point BX = selector
.point ES:EDI = a pointer to the 8-byte buffer for the descriptor copy
.endpoint
.np
If the call succeeds, the carry flag is clear and ES:EDI contains a
pointer to the buffer that contains a copy of the descriptor.
If the call fails, the carry flag is set.
The call fails if the selector passed in BX is invalid or unallocated.
.*
.note Function 000CH
.*
This function copies an 8-byte buffer into the LDT for a specified
descriptor.
The descriptor must first have been allocated with Function 0000H.
Pass the following information:
.begpoint $compact
.point AX = 000CH
.point BX = selector
.point ES:EDI = a pointer to the 8-byte buffer containing the descriptor
.endpoint
.np
If the call succeeds, the carry flag is clear; if it fails, the carry
flag is set.
The call fails if the descriptor passed in BX is invalid.
.np
The type byte, byte 5, has the same format and requirements as the
access rights/type byte passed to Function 0009H in CL.
The format is shown in the first figure presented with the description
of Function 0009H.
.np
The extended type byte, byte 6, has the same format and requirements
as the extended access rights/type byte passed to Function 0009H in
CH, except that the limit field can have any value, and the low order
bits marked
.us reserved
are used to set the upper 4 bits of the descriptor limit.
The format is shown in the second figure presented with the
description of Function 0009H.
.*
.note Function 000DH
.*
This function allocates a specific LDT descriptor.
Pass the following information:
.begpoint $compact
.point AX = 000DH
.point BX = selector
.endpoint
.np
If the call succeeds, the carry flag is clear and the specified
descriptor is allocated.
If the call fails, the carry flag is set.
.np
The call fails if the specified selector is already in use, or if it
is not a valid LDT descriptor.
The first 10h (16 decimal) descriptors are reserved for this function,
and should not be used by the host.
Some of these descriptors may be in use, however, if another client
application is already loaded.
.np
To free the descriptor, use Function 0001H.
.endnote
.*
.section DOS Memory Management Services
.*
.begnote
.*
.note Function 0100H
.*
.ix 'DOS memory management'
.ix 'DPMI' 'allocate DOS memory block'
This function allocates memory from the DOS free memory pool.
This function returns both the real-mode segment and one or more
descriptors that can be used by protected-mode applications.
Pass the following information:
.begpoint $compact
.point AX = 0100H
.point BX = the number of paragraphs (16-byte blocks) requested
.endpoint
.np
If the call succeeds, the carry flag is clear.
AX contains the initial real-mode segment of the allocated block and
DX contains the base selector for the allocated block.
.np
If the call fails, the carry flag is set.
AX contains the DOS error code.
If memory is damaged, code 07H is returned.
If there is not enough memory to satisfy the request, code 08H is
returned.
BX contains the number of paragraphs in the largest available block of
DOS memory.
.np
If you request a block larger than 64KB, contiguous descriptors are
allocated.
Use Function 0003H to find the value of the increment to the next
descriptor.
The limit of the first descriptor is set to the entire block.
Subsequent descriptors have a limit of 64KB, except for the final
descriptor, which has a limit of
.mono blocksize MOD 64KB.
.np
You cannot modify or deallocate descriptors allocated with this
function.
Function 101H deallocates the descriptors automatically.
.*
.note Function 0101H
.*
.ix 'DPMI' 'free DOS memory block'
This function frees a DOS memory block allocated with function 0100H.