The DPMI - DPMI Interface Library Copyright (c) 1997,98 TMT Development Corp. All Rights Reserved INTRODUCTION ------------ The DOS Protected Mode Interface (DPMI) was defined to allow DOS programs to access the extended memory of PC architecture computers while maintaining system protection. DPMI defines a specific subset of DOS and BIOS calls that can be made by protected mode DOS programs. It also defines a new interface via software interrupt 31h that protected mode programs use to allocate memory, modify descriptors, call real mode software, etc. Any operating system that currently supports virtual DOS sessions should be capable of supporting DPMI without affecting system security. Some DPMI implementations can execute multiple protected mode programs in independent virtual machines. Thus, DPMI applications can behave exactly like any other standard DOS program and can, for example, run in the background or in a window (if the environment supports these features). Programs that run in protected mode also gain all the benefits of virtual memory and can run in 32-bit flat model if desired. DPMI PROCEDURES & FUNCTIONS REFERENCE ------------------------------------- procedure ClearRmRegs (var Regs: TRmRegs) ----------------------------------------- This procedure clears (fills with zero) the Real Mode registers structure. You must do it before you call any function, which uses it! See the TESTLBF.PAS and EXEC16.PAS examples. function FarGetByte (Seg: Word; Offs: DWord): Byte -------------------------------------------------- Returns byte value from specified offset of specified protected mode segment (selector). function FarGetWord (Seg: Word; Offs: DWord): Word -------------------------------------------------- Returns word value from specified offset of specified protected mode segment (selector). function FarGetDWord (Seg: Word; Offs: DWord): DWord ---------------------------------------------------- Returns dword value from specified offset of specified protected mode segment (selector). procedure FarPutByte (Seg: Word; Offs: DWord; Value: Byte) ---------------------------------------------------------- Puts byte value to specified offset of specified protected mode segment (selector). procedure FarPutWord (Seg: Word; Offs: DWord; Value: Word) ---------------------------------------------------------- Puts word value to specified offset of specified protected mode segment (selector). procedure FarPutDWord (Seg: Word; Offs: DWord; Value: DWord) ------------------------------------------------------------ Puts dword value to specified offset of specified protected mode segment (selector). function GetCS: Word --------------------- Returns current code segment. function GetDS: Word --------------------- Returns current data segment. function AllocateDescriptors (NumberOfDescriptors: Word): Word -------------------------------------------------------------- This function is used to allocate one or more descriptors from the task's Local Descriptor Table (LDT). The descriptor(s) allocated must be initialized by the application. Entry: NumberOfDescriptors - Number of descriptors to allocate Exit: if successful: Base selector (use SelctorInc to asscss to next selector) if failed : Zero function CreateDataDescriptor (Base, Limit: DWord): Word -------------------------------------------------------- This function is used to allocate one data descriptor from the task's Local Descriptor Table (LDT) with specified Base and Limit Entry: Base - Specified Base Limit - Specified limit Exit: if successful: Data Selector if failed : Zero function CreateCodeDescriptor (Base, Limit: DWord): Word -------------------------------------------------------- This function is used to allocate one code descriptor from the task's Local Descriptor Table (LDT) with specified Base and Limit Entry: Base - Specified Base Limit - Specified limit Exit: if successful: Code Selector if failed : Zero function FreeDescriptor (Selector: Word): Boolean ------------------------------------------------- This function is used to free descriptors that were allocated through the Allocate LDT Descriptors function. Entry: Selector - selector to free Exit : if successful: TRUE if failed : FALSE function SegmentToDescriptor (Segment: Word): Word -------------------------------------------------- This function is used to convert real mode segments into descriptors that are addressable by protected mode programs. Entry: Segment - Real mode segment address Exit : if successful: Selector mapped to real mode segment if failed : Zero function SelectorInc: Word -------------------------- Some functions such as allocate LDT descriptors and allocate DOS memory can return more than one descriptor. You must call this function to determine the value that must be added to a selector to access the next descriptor in the array. Entry: None Exit : if successful: Value to add to get to next selector if failed : Zero function GetSegmentBaseAddress (Selsctor: Word): DWord ------------------------------------------------------ This function returns the 32-bit linear base address of the specified segment. Entry: Selector - Defined selector Exit : if successful: 32-bit linear base address of segment if failed : Zero function SetSelectorBaseAddress (Selector: Word; Base: DWord): Boolean ---------------------------------------------------------------------- This function changes the 32-bit linear base address of the specified selector. Entry: Selector - Defined selector Base - 32-bit linear base address for segment Exit : if successful: TRUE if failed : FALSE function SetSelectorLimit (Selector: Word; Limit: DWord): Word -------------------------------------------------------------- This function sets the limit for the specified segment. Entry: Selector - Defined selector Limit - 32-bit segment limit Exit : if successful: Segment if failed : Zero function GetSelectorAccessRights (Selector: Word): Word ------------------------------------------------------- This function returns access rights and type fields of a descriptor. Entry: Selector - Defined selector Rights - 80386 access rights/type word Exit : if successful: Access rights if failed: Zero function SetSelectorAccessRights (Selector,Rights: Word): Boolean ----------------------------------------------------------------- This function allows a protected mode program to modify the access rights and type fields of a descriptor. Entry: Selector - Defined selector Rights - 80386 access rights/type word Exit : if successful: TRUE if failed: FALSE function CreateCodeAlias (Selector: Word): Word ----------------------------------------------- This function will create a code descriptor that has the same base and limit as the specified code segment descriptor. Entry: Selector - Data segment selector Exit : if successful: Alias selector if failed: Zero function CreateDataAlias (Selector: Word): Word ----------------------------------------------- This function will create a code descriptor that has the same base and limit as the specified code segment descriptor. Entry: Selector - Data segment selector Exit : if successful: Alias selector if failed: Zero function GetDescriptor (Selector: Word; var Descriptor: TDescriptor): Boolean ----------------------------------------------------------------------------- This function copies the descriptor table entry for a specified descriptor into an eight byte buffer. Entry: Selector - Defined selector Descriptor - Pointer to an 8 byte buffer to receive copy of descriptor Exit : if successful: TRUE if failed: FALSE function SetDescriptor (Selector: Word; var Descriptor: TDescriptor): Boolean ----------------------------------------------------------------------------- This function copies an eight byte buffer into the LDT entry for a specified descriptor. Entry: Selector - Defined selector Descriptor - Pointer to an 8 byte buffer that contains descriptor Exit : if successful: TRUE if failed: FALSE function AllocateSpecificDescriptor (Selector: Word): Boolean ------------------------------------------------------------- This function is used to allocate one specific LTD descriptor. Entry: Selector - Selector to allocate Exit: if successful: TRUE if failed : FALSE function AllocDOSmemoryBlock (SizeInBytes: DWord): DWord -------------------------------------------------------- This function will allocate a block of memory from the DOS free memory pool. It returns both the real mode segment and one or more descriptors that can be used by protected mode applications to access the block. Entry: SizeInBytes - Number of bytes desired Exit : if successful: Paragraph-segment value in its high-order word and a selector in its low-order word if failed: Zero function FreeDOSMemoryBlock (Selector: Word): Boolean ----------------------------------------------------- This function frees memory that was allocated through the Allocate DOS Memory Block function. Entry: Selector - Selector of block to free Exit : if successful: TRUE if failed: FALSE function ResizeDOSmemoryBlock (Selector: Word; NewSize: DWord): Boolean ----------------------------------------------------------------------- This function is used to grow or shrink a memory block that was allocated through the AllocateDOSmemoryBlock function. Entry: NewSize - New block size in bytes Selector - Selector of block to modify Exit : if successful: TRUE if failed: FALSE function DOSMemoryAlloc (SizeInBytes: DWord): Word -------------------------------------------------- This function will allocate a block of memory from the DOS free memory pool. It returns real mode only segment of alloceted DOS memory block. Entry: SizeInBytes - Number of bytes desired Exit : if successful: Paragraph-segment value if failed: Zero Note: To get access to allocated DOS memory block you should multiply the returned Paragrapf-segment by 16 and add _zero value. Example: function MkDOSPointer (Segment: Word): Pointer; begin Result:=DWord(Segment)*16+_zero; end. This function makes a protected mode pointer on a given segment of allocated DOS memory block. function DOSMemoryFree (Segment: Word): Boolean ----------------------------------------------- This function frees memory that was allocated through the DOSMemoryAlloc function. Entry: Segment - Real mode segment of block to free Exit : if successful: TRUE if failed: FALSE Remarks: DOSMemoryAlloc and DOSMemoryFree functions uses Int 21h and do not require DPMI function 100h, which is not supported by PMODE.EXE extender. DOSMemoryAlloc and DOSMemoryFree will work correctly in RAW DOS. function GetRealModeIntVec (IntNo: Byte; var RSeg,ROfs: Word): Boolean ---------------------------------------------------------------------- This function returns the value of the current task's real mode interrupt vector for the specified interrupt. Entry: IntNo - Interrupt number Exit : if successful: TRUE RSeg - Segment of real mode interrupt handler ROfs - Offset of real mode interrupt handler if failed: FALSE function SetRealModeIntVec (IntNo: Byte; RSeg,ROfs: Word): Boolean ------------------------------------------------------------------ This function sets the value of the current task's real mode interrupt vector for the specified interrupt. Entry: IntNo - Interrupt number RSeg - Segment of real mode interrupt handler ROfs - Offset of real mode interrupt handler Exit : if successful: TRUE if failed: FALSE function GetExceptionHandler (ExpFault: Byte; var Sel: Word; var Offs: DWord): Boolean -------------------------------------------------------------------------------------- This function returns the Pointer to the current protected mode exception handler for the specified exception number. Entry: ExpFault - Exception/fault number (00h-1Fh) Exit : if successful: TRUE Sel,Offs: Selector,Offset of exception handler if failed: FALSE function SetExceptionHandler (ExpFault: Byte; Sel: Word; Offs: DWord): Boolean ------------------------------------------------------------------------------ This function allows protected mode applications to intercept processor exceptions that are not handled by the DPMI environment. Programs may wish to handle exceptions such as not present segment faults which would otherwise generate a fatal error. Entry: ExpFault - Exception/fault number (00h-1Fh) Sel,Offs - Selector, Offset of exception handler Exit : if successful: TRUE if failed: FALSE function GetDPMIIntVec (IntNo: Byte; var Sel: Word; var Offs: DWord): Boolean ----------------------------------------------------------------------------- This function returns the ParPointer to the current protected mode interrupt handler for the specified interrupt number. Entry: IntNo - Interrupt number Exit : if successful: TRUE Sel,Offs - Selector,Offset of interrupt handler if failed: FALSE function SetDPMIIntVec (IntNo: Byte; Sel: Word; Offs: DWord): Boolean --------------------------------------------------------------------- This function sets the address of the specified protected mode interrupt vector. Entry: IntNo - Interrupt number Addr - Pointer of interrupt handler Exit : if successful: TRUE if failed: FALSE function RealModeInt (IntNo: Byte; var Regs: TRmRegs): Boolean -------------------------------------------------------------- This function simulates an interrupt in real mode. It will invoke the CS:IP specified by the real mode interrupt vector and the handler must return by executing an iret. Entry: IntNo - Interrupt number Regs - TRealRegs structure Exit : if successful: TRUE if failed: FALSE function CallRealModeFar (var Regs: TRmRegs): Boolean ----------------------------------------------------- This function calls a real mode procedure. The called procedure must execute a far return when it completes. Entry: Regs - TRealRegs structure Exit : if successful: TRUE if failed: FALSE function CallRealModeIRet (var Regs: TRmRegs): Boolean ------------------------------------------------------ This function calls a real mode procedure. The called procedure must execute an iret when it completes. Entry: Regs - TRealRegs structure Exit : if successful: TRUE if failed: FALSE function AllocRealModeCallBack (HandlerAddr, RegsAddr: Pointer; var HndSeg: Word; var HndOfs: DWord): Boolean; ------------------------------------------------------------------- This function is used to obtain a unique real mode SEG:OFFSET that will transfer control from real mode to a protected mode procedure. Entry: Linear address of procedure to call Linear address of real mode call structure Exit : if successful: Segment:Offset of real mode call address if failed: Zero function FreeRealModeCallBack (HndSeg: Word; HndOfs: DWord): Boolean; ---------------------------------------------------------- This function frees a real mode call-back address that was allocated through the allocate real mode call-back address service. Entry: HndSeg and HndOfs - segment and offset of real mode call-back address to free Exit : if successful: TRUE if failed: FALSE function GetDPMIVer: Word ------------------------- Returns the version of DPMI services supported. Entry: None Exit : if successful: Version of DPMI service if failed : Zero function GetFreeMemoryInfo (BufferPtr: Pointer): Boolean -------------------------------------------------------- This function is provided so that protected mode applications can determine how much memory is available. Under DPMI implementations that support virtual memory, it is important to consider issues such as the amount of available physical memory. Entry: BufferPtr - Selector:Offset of 30h byte buffer Exit : if successful: TRUE if failed: FALSE function MapPhysicalToLinear (PhysAddr, SizeInBytes: DWord): DWord ------------------------------------------------------------------ This function can be used by device drivers to convert a physical address into a linear address. The linear address can then be used to access the device memory. Entry: PhysAddr - Physical address to map SizeInBytes - Size in bytes of block to map Exit : if successful: Pointer to linear address that can be used to access the physical memory if failed: Nil function GetDisableInterruptState: Boolean ------------------------------------------ This function will disable the virtual interrupt flag and return the previous state of the virtual interrupt flag. Entry: None Exit : Virtual interrupt state function GetEnableInterruptState: Boolean ----------------------------------------- This function will enable the virtual interrupt flag and return the previous state of the virtual interrupt flag. Entry: None Exit : Virtual interrupt state function GetInterruptState: Boolean ------------------------------------------------------------------- This function will disable return state of the virtual interrupt flag. Entry: None Exit : Virtual interrupt state