VDDR/2 - Assembler Language Syntax

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Virtual Device Driver Reference for OS/2
Part 1. Overview Introduction Virtual Device Driver Architecture and Operations Part 2. Virtual Device Drivers Base Virtual Device Drivers Installable Virtual Device Drivers Virtual Mouse Device Driver Part 3. Reference Material C Language Virtual DevHlp Services Appendixes OS/2 Version Compatibility Considerations Assembler Language Syntax Notices Glossary

This appendix categorizes the assembler language versions of all virtual DevHlp services in following list and in subsequent sections. These APIs are counterparts of the C language services listed in C Language Virtual DevHlp Services.

A detailed description of each function follows the #Virtual DevHlp Services by Category.

Function	Type
#VDHAllocBlock	byte-granular memory management service
#VDHAllocDMABuffer	DMA service
#VDHAllocDOSMem	byte-granular memory management service
#VDHAllocHook	hook management service
#VDHAllocMem	byte-granular memory management service
#VDHAllocPages	page-granular memory management service
#VDHArmBPHook	hook management service
#VDHArmContextHook	hook management service
#VDHArmReturnHook	hook management service
#VDHArmSTIHook	hook management service
#VDHArmTimerHook	timer service
#VDHArmVPMBPHook	DPMI service
#VDHBeginUseVPMStack	DPMI service
#VDHCallOutDMA	DMA service
#VDHChangeVPMIF	DPMI service
#VDHCheckPagePerm	DPMI service
#VDHCheckVPMIntVector	DPMI service
#VDHClearVIRR	virtual interrupt service
#VDHClose	file or device I/O service
#VDHCloseVDD	inter-device communication service
#VDHCloseVIRQ	virtual interrupt service
#VDHCopyMem	byte-granular memory management service
#VDHCreateBlockPool	byte-granular memory management service
#VDHCreateSel	GDT selector service
#VDHCreateSem	semaphore service
#VDHDecodeProperty	DOS settings service
#VDHDestroyBlockPool	byte-granular memory management service
#VDHDestroySel	GDT selector service
#VDHDestroySem	semaphore service
#VDHDevBeep	miscellaneous virtual DevHlp service
#VDHDevIOCtl	file or device I/O service
#VDHDisarmTimerHook	timer service
#VDHEndUseVPMStack	DPMI service
#VDHEnumerateVDMs	miscellaneous virtual DevHlp service
#VDHExchangeMem	byte-granular memory management service
#VDHFindFreePages	page-granular memory management service
#VDHFreeBlock	byte-granular memory management service
#VDHFreeDMABuffer	DMA service
#VDHFreeHook	hook management service
#VDHFreeMem	byte-granular memory management service
#VDHFreePages	page-granular memory management service
#VDHFreezeVDM	DOS session control service
#VDHGetCodePageFont	miscellaneous virtual DevHlp service
#VDHGetDirtyPageInfo	page-granular memory management service
#VDHGetError	miscellaneous virtual DevHlp service
#VDHGetFlags	miscellaneous virtual DevHlp service
#VDHGetSelBase	DPMI service
#VDHGetVPMExcept	DPMI service
#VDHGetVPMIntVector	DPMI service
#VDHHaltSystem	DOS session control service
#VDHHandleFromPID	miscellaneous virtual DevHlp service
#VDHHandleFromSGID	miscellaneous virtual DevHlp service
#VDHInstallFaultHook	page-granular memory management service
#VDHInstallIntHook	hook management service
#VDHInstallIOHook	hook management service
#VDHInstallUserHook	hook management service
#VDHIsVDMFrozen	DOS session control service
#VDHKillVDM	DOS session control service
#VDHLockMem	memory-locking memory management service
#VDHMapPages	page-granular memory management service
#VDHOpen	file or device I/O service
#VDHOpenPDD	inter-device communication service
#VDHOpenVDD	inter-device communication service
#VDHOpenVIRQ	virtual interrupt service
#VDHPhysicalDisk	file or device I/O service
#VDHPopInt	v8086 stack manipulation service
#VDHPopRegs	v8086 stack manipulation service
#VDHPopStack	v8086 stack manipulation service
#VDHPopup	miscellaneous virtual DevHlp service
#VDHPostEventSem	semaphore service
#VDHPrintClose	parallel port and printer service
#VDHPushFarCall	v8086 stack manipulation service
#VDHPushInt	v8086 stack manipulation service
#VDHPushRegs	v8086 stack manipulation service
#VDHPushStack	v8086 stack manipulation service
#VDHPutSysValue	miscellaneous virtual DevHlp service
#VDHQueryFreePages	page-granular memory management service
#VDHQueryHookData	hook management service
#VDHQueryLin	miscellaneous virtual DevHlp service
#VDHQueryKeyShift	keyboard service
#VDHQueryProperty	DOS settings service
#VDHQuerySel	GDT selector service
#VDHQuerySem	semaphore service
#VDHQuerySysValue	miscellaneous virtual DevHlp service
#VDHQueryVIRQ	virtual interrupt service
#VDHRaiseException	DPMI service
#VDHRead	file or device I/O service
#VDHReadUBuf	DPMI service
#VDHReallocPages	page-granular memory management service
#VDHRegisterAPI	Register API handler
#VDHRegisterDMAChannel	DMA service
#VDHRegisterProperty	DOS settings service
#VDHRegisterVDD	inter-device communication service
#VDHReleaseCodePageFont	miscellaneous virtual DevHlp service
#VDHReleaseMutexSem	semaphore service
#VDHRemoveFaultHook	page-granular memory management service
#VDHRemoveIOHook	hook management service
#VDHReportPeek	idle DOS application management service
#VDHRequestMutexSem	semaphore service
#VDHRequestVDD	inter-device communication service
#VDHReservePages	page-granular memory management service
#VDHResetEventSem	semaphore service
#VDHSeek	file or device I/O service
#VDHSendVEOI	virtual interrupt service
#VDHSetDosDevice	miscellaneous virtual DevHlp service
#VDHSetError	miscellaneous virtual DevHlp service
#VDHSetFlags	miscellaneous virtual DevHlp service
#VDHSetIOHookState	hook management service
#VDHSetPriority	DOS session control service
#VDHSetVIRR	virtual interrupt service
#VDHSetVPMExcept	DPMI service
#VDHSetVPMIntVector	DPMI service
#VDHSwitchToVPM	DPMI service
#VDHSwitchToV86	DPMI service
#VDHThawVDM	DOS session control service
#VDHUnlockMem	memory-locking memory management service
#VDHUnreservePages	page-granular memory management service
#VDHWaitEventSem	semaphore service
#VDHWaitVIRRs	virtual interrupt service
#VDHWakeIdle	idle DOS application management service
#VDHWakeVIRRs	virtual interrupt service
#VDHWrite	file or device I/O service
#VDHWriteUBuf	DPMI service
#VDHYield	DOS session control service

Virtual DevHlp Services by Category

Virtual DevHlp services can be divided into categories based on the type of service the virtual DevHlp provides. These categories are:

DMA Services

Function	Type
#VDHAllocDMABuffer	Allocate DMA buffer
#VDHCallOutDMA	Call virtual DMA device driver
#VDHFreeDMABuffer	Free DMA buffer
#VDHRegisterDMAChannel	Register DMA channel

DOS Session Control Services

Function	Type
#VDHFreezeVDM	Freeze DOS session
#VDHHaltSystem	Cause system halt
#VDHIsVDMFrozen	Determine if DOS session is frozen
#VDHKillVDM	Terminate DOS session
#VDHSetPriority	Adjust DOS session scheduler priority
#VDHThawVDM	Allow frozen DOS session to resume executing
#VDHYield	Yield the processor.

DOS Settings Services

Function	Type
#VDHDecodeProperty	Decode property string
#VDHQueryProperty	Query virtual device driver property value
#VDHRegisterProperty	Register virtual device driver property

DPMI Services

Function	Type
#VDHArmVPMBPHook	Obtain address of DOS session protected-mode breakpoint
#VDHBeginUseVPMStack	Begin using DOS session protected-mode stack
#VDHChangeVPMIF	Change virtual Interrupt Flag (IF)
#VDHCheckPagePerm	Check Ring 3 page permissions
#VDHCheckVPMIntVector	Determine if DOS session protected-mode handler exists
#VDHEndUseVPMStack	End use of DOS session protected-mode stack
#VDHGetSelBase	Get flat base address
#VDHGetVPMExcept	Get DOS session protected-mode exception vector
#VDHGetVPMIntVector	Return DOS session protected-mode interrupt vector
#VDHRaiseException	Raise an exception to a DOS session
#VDHReadUBuf	Read from protected-mode address space
#VDHSetVPMExcept	Set DOS session protected-mode exception vector
#VDHSetVPMIntVector	Set DOS session protected-mode interrupt vector
#VDHSwitchToVPM	Switch DOS session to protected mode
#VDHSwitchToV86	Switch DOS session to V86 mode
#VDHWriteUBuf	Write to protected-mode address space

Note

"VPM", as found in the function names above, stands for Virtual Protected Mode.

File or Device I/O Services

Function	Type
#VDHClose	Close a file handle
#VDHDevIOCtl	Issue device-specific commands
#VDHOpen	Open a file or device
#VDHPhysicalDisk	Get information about partitionable disks
#VDHRead	Read bytes from file or device
#VDHSeek	Move read or write file pointer for a handle
#VDHWrite	Write bytes to file or device

GDT Selector Services

Function	Type
#VDHCreateSel	Create GDT selector to map a linear range
#VDHDestroySel	Destroy GDT selector
#VDHQuerySel	Get selector for data or stack address

Hook Management Services

Function	Type
#VDHAllocHook	Allocate hooks needed for interrupt simulation
#VDHArmBPHook	Obtain address of V86 breakpoint
#VDHArmContextHook	Set local or global context hook
#VDHArmReturnHook	Set handler to receive control
#VDHArmSTIHook	Set handler to receive control
#VDHFreeHook	Disarm and free hook
#VDHInstallIntHook	Set handler for V86 interrupt
#VDHInstallIOHook	Install I/O port hooks
#VDHInstallUserHook	Install handler for DOS session event
#VDHQueryHookData	Returns pointer to hook reference data
#VDHRemoveIOHook	Remove hooks for PIC I/O ports
#VDHSetIOHookState	Enable/disable I/O port trapping

Idle DOS Application Management Services

Function	Type
#VDHReportPeek	Report DOS session polling activity
#VDHWakeIdle	Wake up DOS session

Note: The services above indicate when a DOS application appears to be idle, and when activity exists that could make the DOS application busy.

Inter-Device Communication Services

DevHlp services

Function	Type
#VDHCloseVDD	Close virtual device driver
#VDHOpenPDD	Open physical device driver
#VDHOpenVDD	Open virtual device driver
#VDHRegisterVDD	Register virtual device driver entry points
#VDHRequestVDD	Issue request for virtual device driver operation

Keyboard Services

Function	Type
#VDHQueryKeyShift	Query keyboard shift state

Memory Management Services

There are three sub-categories of the memory management virtual DevHlp services. The first two are used for the granularity of the memory allocation unit, the third category is used for memory-locking services.

Byte-Granular Memory Management Services

Function	Type
#VDHAllocBlock	Allocate block from memory block pool
#VDHAllocDOSMem	Allocate block of memory from DOS area
#VDHAllocMem	Allocate small amount of memory
#VDHCopyMem	Copy from one linear memory address to another
#VDHCreateBlockPool	Create memory block pool
#VDHDestroyBlockPool	Destroy memory block pool
#VDHExchangeMem	Exchange contents of two linear memory regions
#VDHFreeBlock	Free block of memory
#VDHFreeMem	Free memory

Page-Granular Memory Management Services

Function	Type
#VDHAllocPages	Allocate page-aligned memory object
#VDHFindFreePages	Find largest available linear memory
#VDHFreePages	Free memory object
#VDHGetDirtyPageInfo	Return status of dirty bits
#VDHInstallFaultHook	Install page fault handler
#VDHMapPages	Map specified linear address
#VDHQueryFreePages	Return amount of free virtual memory
#VDHReallocPages	Reallocate memory object
#VDHRemoveFaultHook	Remove page fault handler
#VDHReservePages	Reserve range of linear addresses
#VDHUnreservePages	Unreserve range of linear addresses

Memory-Locking Memory Management Services

Function	Type
#VDHLockMem	Verify access or lock memory
#VDHUnlockMem	Release memory lock

Note

The services above allow virtual device drivers to allocate, free, reallocate, and lock memory for global, per-DOS session, page-granular, or byte-granular objects.

Four types of mappings are supported:

Mapping to a physical address

Mapping to another linear address

Mapping to black holes (don't care) pages

Mapping to invalid (unmapped) pages

Note

Virtual device drivers can also request smaller memory allocations from the kernel heap, which is global and fixed. Small, fixed size block services are available to speed up frequent allocations and freeing of memory. For a particular block size, a pool of blocks is maintained and the requirements are met by taking off a block from the block pool.

Miscellaneous Virtual DevHlp Services

Function	Type
#VDHDevBeep	Device beep virtual DevHlp service
#VDHEnumerateVDMs	Run worker function for each DOS session
#VDHGetCodePageFont	Return information of DOS session code page font
#VDHGetError	Get error code from last virtual DevHlp service
#VDHGetFlags	Get DOS Session's EFLAGS Register
#VDHHandleFromPID	Get handle for given Process ID
#VDHHandleFromSGID	Get DOS session handle from Screen Group ID
#VDHPopup	Display message
#VDHPutSysValue	Set system value
#VDHQueryLin	Get linear address for Far16 address
#VDHQuerySysValue	Query system value
#VDHRegisterAPI	Register API handler
#VDHReleaseCodePageFont	Release code page font
#VDHSetDosDevice	Register/install DOS device driver
#VDHSetError	Set error code
#VDHSetFlags	Set DOS session flags register

Parallel Port and Printer Services

Function	Type
#VDHPrintClose	Flush and close open printers for DOS session

Semaphore Services

Function	Type
#VDHCreateSem	Create event or mutex semaphore
#VDHDestroySem	Destroy semaphore
#VDHPostEventSem	Post event semaphore
#VDHQuerySem	Query semaphore state
#VDHReleaseMutexSem	Release mutex semaphore
#VDHRequestMutexSem	Request mutex semaphore
#VDHResetEventSem	Reset event semaphore
#VDHWaitEventSem	Wait on event semaphore

Note: These semaphore services above are used for synchronizing with an OS /2 process. Virtual device drivers must be careful not to block ( VDHRequestMutexSem/VDHWaitEventSem) in the context of a DOS session task; otherwise, that task will receive no more simulated hardware interrupts until it becomes unblocked.

Timer Services

Function	Type
#VDHArmTimerHook	Set timer service/handler
#VDHDisarmTimerHook	Cancel timer service

Virtual Interrupt Services

Function	Type
#VDHClearVIRR	Clear virtual IRR
#VDHCloseVIRQ	Deregister IRQ handler
#VDHOpenVIRQ	Register IRQ handler
#VDHQueryVIRQ	Query IRQ status on a DOS session
#VDHSendVEOI	Send virtual EOI to VPIC
#VDHSetVIRR	Set virtual interrupt request register (IRR)
#VDHWaitVIRRs	Wait until interrupt is simulated
#VDHWakeVIRRs	Wake up DOS session

V8086 Stack Manipulation Services

Function	Type
#VDHPopInt	Remove IRET frame from client DOS session stack
#VDHPopRegs	Pop client DOS session registers from client stack
#VDHPopStack	Pop data off client stack
#VDHPushFarCall	Simulate FAR call to V86 code
#VDHPushInt	Transfer control to V86 interrupt handler
#VDHPushRegs	Push client DOS session registers onto client stack
#VDHPushStack	Push data onto client stack

VDHAllocBlock

Format

This function allocates a block from the specified memory block pool. This block is allocated from fixed or swappable memory, depending on the value of the OptionFlag flag when the block is created with VDHCreateBlockPool.

include mvdm.inc
EXTERN VDHAllocBlock:NEAR
SourceBlockPool DD ?      ; Handle to a memory block pool
PUSH SourceBlockPool      ; Push SourceBlockPool
CALL VDHAllocBlock        ; Call the function

Parameters

SourceBlockPool (DD) Handle to the pool of memory blocks from which to allocate a memory block.

Return Codes

Success: If the function is successful, it returns the address of the allocated memory block.

Failure: If the function fails, it returns 0. VDHGetError should be called to determine the nature of the problem. Note that passing an invalid memory block handle causes a system halt to occur.

Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: Any blocks allocated by a virtual device driver for use by the terminating DOS session are freed by using VDHFreeBlock. Any block pools created for the DOS session should also be freed.

VDHAllocDMABuffer

Format

This function allocates a DMA buffer.

include mvdm.inc
EXTERN VDHAllocDMABuffer:NEAR
RequestSize DD ?       ; Request size
Align64kFlag DD ?      ; Alignment flag
PhysAddrPtr DD ?       ; Location to store the physical address returned

PUSH RequestSize       ; Push RequestSize
PUSH Align64kFlag      ; Push Align64kFlag
PUSH PhysAddrPtr       ; Push PhysAddrPtr

CALL VDHAllocDMABuffer ; Call the function

Parameters

RequestSize (DD) Request Size.

If the Align64kFlag =1, RequestSizeis always less than or equal to 64KB. If the Align64kFlag =0, RequestSize is always less than or equal to 128KB.

Align64kFlag (DD) Alignment flag.

If Align64kFlag =1, the buffer is at a 64KB alignment in physical memory. If Align64kFlag =0, the buffer is at a 128KB alignment in physical memory.

PhysAddrPtr (DD) Location where VDHAllocDMABuffer returns the physical address of the allocation.

Return Codes

Success: If the function is successful, it returns the linear address of allocation (system memory).

Failure: If the function fails, it returns -1. VDHGetError should be called to determine the nature of the problem.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: The virtual device driver frees the buffer by using VDHFreeDMABufferat DOS session termination.

Notes

Physical memory is allocated resident and contiguous, and is always in the first 16MB. The Linear Memory range comes from the system arena. The contents of the returned buffer are not important; that is, the buffer is not zero-filled.

VDHAllocDOSMem

Format

This function allocates a block of memory from the DOS memory area. Allocations start at 0 bytes and go to 256KB.

include mvdm.inc
EXTERN VDHAllocDOSMem:NEAR
BlockSize DD ?       ; Size of the desired memory block (in bytes) 
PUSH BlockSize       ; Push BlockSize

CALL VDHAllocDOSMem  ; Call the function

Parameters

BlockSize (DD) Size of the desired memory block; the number of bytes to allocate.

Return Codes

Success: If the function is successful, it returns the address of the allocated memory block.

Failure: If the function fails, it returns 0. VDHGetError should be called to determine the nature of the problem. If BlockSize = 0, or if the function is called in an invalid context (see "Context Issues" below), a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context (DOS session creation).

DOS Session Terminations: There are no DOS session termination implications for this function. The DOS Session Manager frees this memory.

Notes: There is no way to free memory taken from the DOS heap. If there is no free memory in the DOS memory area, the allocation fails. Allocations always start on paragraph (16-byte) boundaries.

VDHAllocHook

Format

This function is used to allocate a hook handle for the arm hook services: Context, STI, Return, Timer, and BP (breakpoint).

include mvdm.inc

EXTERN VDHAllocHook:NEAR
HookType DD ?     ; Hook type
ArmHookFcn DD ?   ; Arm hook function
RefDataSize DD ?  ; Size of the reference data

PUSH HookType     ; Push HookType
PUSH ArmHookFcn   ; Push ArmHookFcn
PUSH RefDataSize  ; Push RefDataSize

CALL VDHAllocHook ; Call the function

Parameters

HookType (DD) Hook type.

Possible values are:

VDH_CONTEXT_HOOK	VDHArmContextHook
VDH_STI_HOOK	VDHArmSTIHook
VDH_RETURN_HOOK	VDHArmReturnHook
VDH_TIMER_HOOK	VDHArmTimerHook
VDH_BP_HOOK	VDHArmBPHook

ArmHookFcn (DD) Arm hook function.

RefDataSize (DD) Size of the reference data.

Return Codes

Success: If the function is successful, it returns a hook handle, which is used in the Arm services.

Failure: If there is an error, the function returns NULL. VDHGetError should be called to determine the nature of the problem. If HookType or ArmHookFcn is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization or DOS session-task context. However, VDH_RETURN_HOOK and VDH_BP_HOOK require the DOS session-task context.

DOS Session Terminations: During initialization time, hooks are allocated globally; that is, they are not associated with a DOS session process. These hooks are not automatically freed when a DOS session terminates. During DOS session creation time or thereafter, allocated hooks are associated with the current DOS session, and are freed when that DOS session terminates.

Notes: Use VDHQueryHookData to get a pointer to any reference data allocated.

VDHAllocMem

Format

This function allocates a small amount of memory on a LONG/DWORD boundary. The memory is allocated from the system area, so the address is valid in all process contexts.

include mvdm.inc
EXTERN VDHAllocMem:NEAR
NumBytes DD ?
OptionFlag DD ?  ; Number of bytes to allocate
PUSH NumBytes    ; Push NumBytes
PUSH OptionFlag  ; Push OptionFlag

CALL VDHAllocMem ; Call the function

Parameters

NumBytes (DD) Number of bytes to allocate.

OptionFlag (DD) Bit flag describing the allocation options.

Possible value: VDHAM_SWAPPABLE Allocate memory from the swappable heap. Otherwise, memory is allocated from the fixed heap and can be accessed at hardware interrupt time.

Return Codes

Success: If the function is successful, it returns the address of the allocated space.

Failure: If the function fails, it returns 0. VDHGetError should be called to determine the nature of the problem. If either NumBytes or OptionFlag is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: All memory allocated by a virtual device driver for use by the terminating DOS session is freed by using VDHFreeMem.

Notes: Allocations larger than one page are performed by using VDHAllocPages. To access the allocated memory at hardware interrupt time, be sure to allocate memory from the fixed heap.

VDHAllocPages

Format

This function allocates a page-aligned, page-granular memory object.

include mvdm.inc

EXTERN VDHAllocPages:NEAR
StartingAddress DD ? ; A specific linear address
NumPages DD ?        ; The number of pages to allocate
OptionFlag DD ?      ; Allocation options bit-flag

PUSH StartingAddress ; Push StartingAddress
PUSH NumPages        ; Push NumPages
PUSH OptionFlag      ; Push OptionFlag

CALL VDHAllocPages   ; Call the function

Parameters

StartingAddress (DD) A specific address used with the available options ( see Option Flag).

NumPages (DD) Number of pages of linear memory to allocate.

OptionFlag(DD) Bit flag indicating choices in allocation options.

This flag can take one or more of the following values:

VDHAP_SPECIFIC VDHAllocPages attempts to allocate pages starting at the linear address, StartingAddress. Otherwise, an arbitrary linear address is selected.

VDHAP_SYSTEM The linear address is allocated from the system (global) area, essentially allocating global memory. Otherwise, it is allocated from the private area of this process.

VDHAP_FIXED The allocated memory is fixed. Otherwise, the memory is swappable. This flag cannot be used if VDHAP_PHYSICAL is specified.

VDHAP_PHYSICAL The allocated linear address range maps the physical address range, starting at StartingAddress. Otherwise, an arbitrary physical page is assigned. Note that this flag cannot be used if VDHAP_FIXED is specified .

Return Codes

Success: If the function is successful, it returns the address of the allocated memory.

Failure: If the function fails, it returns 0. VDHGetError should be called to determine the nature of the problem. If the OptionFlag flag is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization or task context. If called in the initialization context, VDHAP_SYSTEM must be specified. If called in the OS/2 task context, VDHAP_SYSTEM must also be specified.

DOS Session Terminations: Any allocations that are not in the terminating DOS sessions private area must be released by using VDHFreePages.

Notes: When an allocation made with VDHAllocPagesis shrunk by VDHReallocPages, the linear range between the end of the allocation and the original end of the allocation remains available for object growth without movement. Regardless of VDHReallocPages activity, all pages in the allocation retain the same properties (that is fixed, system, and physical) .

VDHArmBPHook

Format

This function obtains the address of the V86 breakpoint allocated by a previous call to VDHAllocHook with the VDH_BP_HOOK flag.

include mvdm.inc
EXTERN VDHArmBPHook:NEAR
HookHandle DD ? ; Hook handle
PUSH HookHandle ; Push HookHandle 
CALL VDHArmBPHook ; Call the function

Parameters

HookHandle (DD) Hook handle allocated with VDHAllocHook.

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - p    - Pointer to hook-specific reference data
;           [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT   None
;
; CONTEXT   DOS session-task

Return Codes

Success: If the function is successful, it returns a V86 breakpoint address.

Failure: If HookHandle is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context, and needs to be called only at DOS session creation time.

DOS Session Terminations: There are no DOS session termination implications for this function. BP (breakpoint) hooks are automatically removed during DOS session termination.

Notes: This VDH service provides a raw breakpoint service. Upon entry to the arm hook function, the client's CS:IP is randomly set. Therefore, it is crucial that this function set the CS:IP to a valid address. Typically, the CS:IP is retrieved from the client's stack through use of VDHPopStack. This is a low-level service. Appropriate care should be exercised to ensure that the client's CS:IP and stack remain valid.

Unlike other hooks, breakpoint hooks are armed until explicitly disarmed by a call to VDHFreeHook. When the V86 breakpoint address is called from V86 mode, the hook function is called. Any changes made to the client register frame cause the corresponding registers to take on these values upon return to V86 mode. The p parameter in the hook routine points to the cbRefData bytes of data allocated by VDHAllocHook.

VDHArmContextHook

Format

This function is used to get to a task-time context from interrupt time when an interrupt is simulated. This service adds a handler to the list of routines called the next time the task context is entered (global context), or the next time a specific DOS session-task context is reached (local context). This is done only once the handler is removed from the list after it is executed.

include mvdm.inc
EXTERN VDHArmContextHook:NEAR
HookHandle DD ? ; Hook handle allocated with VDHAllocHook
VDMHandle DD ?  ; DOS session handle
PUSH HookHandle ; Push HookHandle
PUSH VDMHandle  ; Push VDMHandle
CALL VDHArmContextHook ; Call the function

Parameters

HookHandle (DD) Hook handle allocated with VDHAllocHook.

VDMHandle (DD) DOS session handle. A value of -1 indicates a global context.

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;           [ESP + 4] - pcrf     - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   Task (global) or DOS session-task (local)
; NOTE      pcrf is valid only for local context hook handlers

Return Codes

Success: If the function was successful, it returns nothing.

Failure: If HookHandle or VDMHandle is invalid, or if the hook is already armed, a system halt occurs.

Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: Any context hooks allocated in the context of the terminating DOS session are deallocated by the DOS Session Manager.

Notes: After calling this routine, the caller is guaranteed that the context hook will be executed before any user-space code (global context) or any V86 code in the specified DOS session (local context).

VDHArmReturnHook

Format

This function sets a service to receive control when an Interrupt Return (IRET) or Far Return (RETF)instruction is executed in V86 mode or when VDHPopInt is executed.

include mvdm.inc
EXTERN VDHArmReturnHook:NEAR
HookHandle  DD ?      ; Hook handle
RetHookType DD ?      ; Return hook type
PUSH HookHandle       ; Push HookHandle
PUSH RetHookType      ; Push RetHookType
CALL VDHArmReturnHook ; Call the function

Parameters

HookHandle (DD) Hook handles the routine to get control on an IRET/RETF. Allocated with VDHAllocHook.

RetHookType (DD) Return hook type.

Possible values are:

VDHARH_NORMAL_IRET

VDHARH_NORMAL_RET

VDHARH_RECURSIVE_IRET

VDHARH_RECURSIVE_RET

VDHARH_CSEIP_HOOK

VDHARH_RECURSIVE_CSEIP_HOOK

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;           [ESP + 4] - pcrf     - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

Return Codes

Success: If the function was successful it returns a nonzero value.

Failure: If VDHARH_NORMAL_x is already armed, the function returns 0. If HookHandle is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: Any return hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager.

Notes: The VDHARH_NORMAL_RET and VDHARH_RECURSIVE_RET return hook types can be made only after VDHPushFarCall has been called, but before returning to V86 mode. The return hook types, VDHARH_NORMAL_IRET and VDHARH_RECURSIVE_ IRET, can be made only in the following contexts:

• Within a software interrupt handler set by VDHInstallIntHook
• After VDHPushInt has been called, but before returning to V86 mode

The VDHARH_RECURSIVE_x return types push two extra WORDs on the client's stack before the IRET or RET frame. VDHARH_CSEIP_HOOK and VDHARH_RECURSIVE_ CSEIP_HOOK are meant to be used before a VDHPushInt or VDHPushFarCall, as it is more efficient to do this type of return hook first. Only the normal and recursive CS:EIP hooks will work in DOS session protected mode.

VDHArmSTIHook

Format

This function sets a handler to receive control when the current DOS session enables simulated interrupts. This handler is called only once. If interrupts are already enabled in the DOS session, the handler is called immediately.

include mvdm.inc
EXTERN VDHArmSTIHook:NEAR
HookHandle DD ?    ; Hook handle allocated with VDHAllocHook
VDMHandle DD ?     ; DOS session handle
PUSH HookHandle    ; Push HookHandle
PUSH VDMHandle     ; Push VDMHandle
CALL VDHArmSTIHook ; Call the function

Parameters

HookHandle (DD) Hook handle allocated with VDHAllocHook.

VDMHandle (DD) DOS session handle.

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;           [ESP + 4] - pcrf     - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

Return Codes

Success: If the function was successful, it returns nothing.

Failure: If either HookHandle or VDMHandle is invalid, or if the hook is already armed, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: Any STI hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager.

Notes: Interrupt re-enabling detection is performed when the DOS session runs with IOPL = 0. This causes any instructions that might modify the interrupt flag to fault.

VDHArmTimerHook

Format

This function sets a timer handler to be called after a specified period of time has elapsed. The handler is called only once.

include mvdm.inc
EXTERN VDHArmTimerHook:NEAR
HookHandle DD ?      ; Timer hook handle
Duration DD ?        ; Duration of the timeout in milliseconds
VDMHandle DD ?       ; DOS session handle
PUSH HookHandle      ; Push HookHandle
PUSH Duration        ; Push Duration
PUSH VDMHandle       ; Push VDMHandle
CALL VDHArmTimerHook ; Call the function

Parameters

HookHandle (DD) Timer hook handle.

Duration (DD) Timer duration in milliseconds.

VDMHandle (DD) DOS session handle.

Possible values are:

DOS Session Handle or 0 When the specified time duration expires, a local context hook is automatically armed by using the specified HookHandle.

VDH_TIMER_GLOBAL_CONTEXT When the specified time duration expires, a global context hook is automatically armed by using the specified HookHandle.

VDH_TIMER_INTERRUPT_HOOK When the specified time duration expires, the timer hook specified by HookHandle is called at interrupt time.

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pRefData - Pointer to reference data
;    EXIT   None
;
; CONTEXT   Interrupt

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If either Duration or HookHandle is invalid or the hook is already armed, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization, task, or interrupt context.

DOS Session Terminations: Any timer hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager at DOS session termination.

Notes: If type VDH_TIMER_INTERRUPT_HOOK, the timer handler cannot block since it executes at physical interrupt time.

VDHArmVPMBPHook

Format

This function obtains the address of the DOS session's protected-mode breakpoint allocated by a previous call to VDHAllocHook with the VDH_BP_HOOK flag.

include mvdm.inc
EXTERN VDHArmVPMBPHook:NEAR
HookHandle DD ?      ; Hook handle allocated with VDHAllocHook
PUSH HookHandle      ; Push HookHandle
CALL VDHArmVPMBPHook ; Call the function

Parameters

HookHandle (DD) Hook handle allocated with VDHAllocHook.

The hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to hook-specific reference data
;           [ESP + 4] - pcrf - Pointer to client register frame
;
;    EXIT   None
;
; CONTEXT   DOS session-task

Return Codes

Success: If the function is successful, it returns a DOS session protected- mode breakpoint address.

Failure: If HookHandle is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Unlike other hooks, breakpoint hooks are armed until explicitly disarmed by a call to VDHFreeHook. When the breakpoint address is executed from DOS session protected mode, the hook function is called. Any changes made to the client register frame cause the corresponding registers to take on these values after returning to the DOS session. The p parameter in the hook routine points to the RefDataSize bytes of data allocated by VDHAllocHook.

VDHArmVPMBPHook provides a raw breakpoint service. On entry to the arm hook function, the client's CS:EIP is randomly set. It is therefore crucial that the virtual device driver's hook handler sets the CS:EIP to a valid address . Typically, the CS:EIP is retrieved from the client's stack through the use of VDHPopStack, which is a low-level service. Appropriate care should be exercised to ensure that the client's CS:EIP and stack remain valid.

The breakpoint address returned will be valid for all DPMI clients within the DOS session. The breakpoint address may be placed in the DPMI application's IDT (see #VDHSetVPMIntVector), but will have to be rehooked each time a DPMI task starts (see #VDHInstallUserHook).

There must be a protected-mode DPMI client running in the DOS session before calling this function.

VDHBeginUseVPMStack

Format

This function is used to switch to the DOS session's protected-mode stack for hardware interrupts, exceptions, and so forth. This service can be called repeatedly, but only the first call will switch stacks.Subsequent calls increment use, count but remain on the VPM stack.

include mvdm.inc
EXTERN VDHBeginUseVPMStack:NEAR
DD ?
PUSH ; Push
CALL VDHBeginUseVPMStack ; Call the function

Parameters

(DD) None.

Return Codes

None.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: There must be a DPMI client running in the DOS session before calling this function.

VDHCallOutDMA

Format

This function is used by the virtual DMA device driver (VDMA) to check how much DMA transfer has been completed, and to copy the contents from the temporary buffer to the DOS area.

If a virtual device driver owns a DMA channel, it must call the virtual DMA device driver for those interrupts that occur when a DMA request is pending on that channel. This service also indicates when the DOS session is done with the channel so that the channel can be given to another waiting DOS session.

include mvdm.inc
EXTERN VDHCallOutDMA:NEAR
DD ?
PUSH ; Push
CALL VDHCallOutDMA ; Call the function

Parameters

(DD) None.

Return Codes

None.

Purpose

Context Issues: This function can be called in any context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHChangeVPMIF

Format

This function changes the virtual Interrupt Flag (IF) that enables or disables protected-mode interrupts. This change is reflected in a bit in the flVDMStatus kernel variable (see "Notes" under Purpose). If the STI hooks are waiting and interrupts are enabled, the hooks are called.

include mvdm.inc
EXTERN VDHChangeVPMIF:NEAR
SetIFFlag DD ? ; Indicates whether to turn the IF flag on or off
PUSH SetIFFlag ; Push SetIFFlag
CALL VDHChangeVPMIF ; Call the function

Parameters

SetIFFlag (DD) Indicates whether to turn the IF flag ON or OFF. If nonzero, set IF flag to 1 (one). If zero, set IF flag to 0 (zero).

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: Not applicable to this function.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: The flVDMStatus kernel variable is exported from the kernel. Any virtual device driver can refer to it directly. flVDMStatus is a DD-sized variable that contains various DOS session status flags relating to protected mode and the DOS Protected Mode Interface (DPMI).

The flVDMStatus flags indicate:

• DPMI was initialized (protected mode was enabled)
• 16-bit or 32-bit
• The current execution mode (V86 or protected)

These flags and their values are:

VDM_STATUS_VPM_32         0x00000001      /* 32-bit DPMI application   */
VDM_STATUS_VPM_APP        0x00000002      /* DPMI application started  */
VDM_STATUS_VPM_EXEC       0x00000004      /* In DOS session protected mode*/
VDM_STATUS_VPM_IF_FLAG    0x00000010      /* Virtual IF flag           */
VDM_STATUS_VPM_PERM       0x00000080      /* Protected mode allowed?   */
VDM_STATUS_VPM_XDOS       0x00000100      /* DOS API extension active? */

VDHCheckPagePerm

Format

This function checks Ring 3 page permissions for a range of pages. This service fails if a Ring 3 client faults on any of the pages that have been checked.

include mvdm.inc
EXTERN VDHCheckPagePerm:NEAR
BasePage DD ? ; Base virtual page number
Reserved DD ? ; Reserved;must be set to zero
NumPages DD ? ; Number of pages to verify
Flag     DD ? ; Flag
PUSH BasePage ; Push BasePage
PUSH Reserved ; Push Reserved
PUSH NumPages ; Push NumPages
PUSH Flag     ; Push Flag
CALL VDHCheckPagePerm ; Call the function

Parameters

BasePage (DD) Base virtual page number.

Reserved (DD) Reserved. Must be set to 0.

NumPages (DD) Number of pages to verify.

Flag(DD) Values are:

VPMPG_U Are the pages user-accessible?

VPMPG_W Are the pages writable?

VPMPG_R Are the pages readable (valid)?

VPMPG_X Are the pages executable?

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHCheckVPMIntVector

Format

This function returns a nonzero value if the application protected-mode interrupt vector is set.

include mvdm.inc
EXTERN VDHCheckVPMIntVector:NEAR
Vector DD ? ; Interrupt vector number
PUSH Vector ; Push Vector
CALL VDHCheckVPMIntVector ; Call the function

Parameters

Vector (DD) Interrupt vector number.

Return Codes

Success: If the function is successful it returns a nonzero value.

Failure: If there is no user-registered interrupt handler for the interrupt in Vector, the function returns 0 (zero).

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: There must be a DPMI client running in the DOS session before calling this function.

VDHClearVIRR

Format

This function clears the virtual Interrupt Request Register (IRR) in the Virtual Programmable Interrupt Controller (VPIC) of the specified DOS session for the IRQ specified. The simulation of interrupts to the specified DOS session is stopped on this IRQ level.

include mvdm.inc
EXTERN VDHClearVIRR:NEAR
VDMHandle DD ? ; DOS session handle
IRQHandle DD ? ; IRQ handle from VDHOpenVIRQ
PUSH VDMHandle ; Push VDMHandle
PUSH IRQHandle ; Push IRQHandle
CALL VDHClearVIRR ; Call the function

Parameters

VDMHandle (DD) DOS session handle. A value of 0 (zero) indicates the current DOS session.

IRQHandle(DD) IRQ handle from VDHOpenVIRQ.

Return Codes

Success: If the function was successful, it returns nothing.

Failure If either of the parameters is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHClose

Format

This function closes a file or device that was opened with VDHOpen.

include mvdm.inc
EXTERN VDHClose:NEAR
FileHandle DW ? ; Handle to the file or device to close
PUSH FileHandle ; Push FileHandle
CALL VDHClose   ; Call the function

Parameters

FileHandle (DW) Handle (from VDHOpen) to the file or device to close.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If FileHandle is invalid or if the DOS session is not in the DOS session-task context, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: Any handles opened by the virtual device driver for the terminating DOS session must be closed.

VDHCloseVDD

Format

This function closes a virtual device driver/virtual device driver (VDD/VDD ) Inter-Device-Driver Communication (IDC) session that was opened with VDHOpenVDD.

include mvdm.inc
EXTERN VDHCloseVDD:NEAR
VDDHandle DD ?  ; Handle to the file or device to close
PUSH VDDHandle  ; Push VDDHandle
CALL VDHCloseVDD ; Call the function

Parameters

VDDHandle (DD) Handle (from VDHOpenVDD) to the virtual device driver to close.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If VDMHandle is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: If a virtual device driver has a VDD/VDD session for a particular DOS session, that session is closed when the DOS session terminates.

Notes: This service is used to close the type of VDD/VDD connections, which are temporary or are on a per-DOS session basis.

VDHCloseVIRQ

Format

This function closes the virtual IRQ handle passed to it.

include mvdm.inc
EXTERN VDHCloseVIRQ:NEAR
IRQHandl DD ?     ; Handle of the virtual device driver to close
PUSH IRQHandl     ; Push IRQHandl
CALL VDHCloseVIRQ ; Call the function

Parameters

IRQHandl (DD) Handle to the IRQ (from VDHOpenVIRQ) to close.

Return Codes

Success: If the function was successful, it returns nothing.

Failure: If IRQHandle is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the initialization context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHCopyMem

Format

This function copies memory from one user linear address to another.

include mvdm.inc
EXTERN VDHCopyMem:NEAR
Source      DD ? ; Address of the data to copy 
Destination DD ? ; Address to copy the data to
NumBytes    DD ? ; Number of bytes to copy
PUSH Source      ; Push Source
PUSH Destination ; Push Destination
PUSH NumBytes    ; Push NumBytes
CALL VDHCopyMem  ; Call the function

Parameters

Source (DD) Address of the source data to be copied.

Destination (DD) Address to which the data is to be copied.

NumBytes (DD) Number of bytes to copy.

Return Codes

Success: If the function is successful, it returns nothing.

Failure If NumBytes is 0 (zero), a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Protection faults are handled as if a user application had performed the access. Therefore, writing to an invalid page causes a virtual device driver page fault handler to gain control. If there is no virtual device driver fault handler, a "don't care" page is mapped in at the faulting linear address.

Note that touching invalid pages is allowed only in the context of the DOS session. A virtual device driver cannot touch invalid pages through the HVDM (DOS session Handle) alias region if it is not in the context of that DOS session. A virtual device driver that violates this rule causes a system halt.

This function yields the CPU if it is necessary to ensure that the thread dispatch latency limit is not exceeded. This function also supports overlapping linear regions. However, the results are undefined when copying between regions with aliases (through VDHMapPages) to the same physical page.

If necessary, VDHLockMem is used to ensure that the status of the source and destination linear ranges does not change. This is required only if the source and destination ranges are in private DOS session memory (accessed through the HVDM), and the call to VDHCopyMemis made in the context of some other process.

VDHCreateBlockPool

Format

This function creates a pool of memory blocks of a specified size. The blocks are allocated from the system area so that the block addresses are valid in all process contexts.

include mvdm.inc
EXTERN VDHCreateBlockPool:NEAR
BlockSize  DD ? ; Size of block to initialize (in bytes)
OptionFlag DD ? ; Allocation options bit flag
PUSH BlockSize  ; Push BlockSize
PUSH OptionFlag ; Push OptionFlag
CALL VDHCreateBlockPool ; Call the function

Parameters

BlockSize (DD) Size of block to initialize (in bytes).

OptionFlag (DD) Allocation options bit flag. Possible value:

VDHCBP_SWAPPABLE Blocks are allocated from the swappable heap. Otherwise, blocks are allocated from the fixed heap and can be accessed at hardware interrupt time.

Return Codes

Success: If the function is successful, it returns a handle to the pool of memory blocks.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If OptionFlag is invalid, or if BlockSize is equal to 0 (zero), a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: Any block pools allocated by a virtual device driver for use by the terminating DOS session is freed by using VDHDestroyBlockPool.

VDHCreateSel

Format

This function creates a GDT selector that maps a linear range. This service is used to create a 16:16 pointer, which is passed to a 16-bit physical device driver.

include mvdm.inc
EXTERN VDHCreateSel:NEAR
LinearAddress DD ? ; Linear address of the start of the buffer
BufferSize    DD ? ; Size of the buffer in bytes
PUSH LinearAddress ; Push LinearAddress
PUSH BufferSize    ; Push BufferSize
CALL VDHCreateSel  ; Call the function

Parameters

LinearAddress (DD) Linear address of the beginning of the buffer.

BufferSize (DD) Size of the buffer in bytes. The expected range is 0-65535 with 0 interpreted as 65536.

Return Codes

Success: If the function is successful, it returns a nonzero selector value such that SELECTOR:0 points to the first byte of the linear range.

Failure: If BufferSize is greater than 65535 or if there are no more selectors available, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: Any selectors created to map memory in the terminating DOS session must be destroyed with VDHDestroySel. The virtual device driver must ensure that any physical device driver that was given these selectors is finished with them.

Notes: The linear address must be in system memory. To create a 16:16 pointer to a DOS session address (in the 0 to 1MB+64KB range), use the HVDM (DOS session handle) alias linear address. VDHDestroySel must be called when finished with this pointer.

VDHCreateSem

Format

This function is used to create an event or mutex semaphore.

include mvdm.inc
EXTERN VDHCreateSem:NEAR
SemHandlePointer DD ? ; Semaphore handle address
SemType          DD ? ; Type of semaphore of create
PUSH SemHandlePointer ; Push SemHandlePointer
PUSH SemType          ; Push SemType
CALL VDHCreateSem     ; Call the function

Parameters

SemHandlePointer (DD) Semaphore handle address.

SemType (DD) Type of semaphore to create.

Values are:

VDH_EVENTSEM Event semaphore

VDH_MUTEXSEM Mutex semaphore

Return Codes

Success: If the function is successful, it returns a nonzero value and places a handle to the semaphore in SemHandlePointer.

Failure: If the function fails, it returns 0. VDHGetError should be called to determine the nature of the problem. An invalid semaphore type causes a system halt to occur.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: These semaphores are global and are not attached to a specific DOS session. If a virtual device driver maintains semaphores on a per-DOS session basis, it destroys the semaphores by using VDHDestroySem when the DOS session they are associated with is terminated.

VDHDecodeProperty

Format

This function decodes the specified format of a property string. (See Notes)

include mvdm.inc
EXTERN VDHDecodeProperty:NEAR
ppProperty     DD ? ; Pointer to a pointer to property string
StartNumberPtr DD ? ; Location to return the starting number
EndNumberPtr   DD ? ; Location to return the ending number
BaseFlag       DD ? ; Flag indicating the numeric base to use
PUSH ppProperty     ; Push ppProperty
PUSH StartNumberPtr ; Push StartNumberPtr
PUSH EndNumberPtr   ; Push EndNumberPtr
PUSH BaseFlag       ; Push BaseFlag
CALL VDHDecodeProperty ; Call the function

Parameters

ppProperty (DD) A pointer to a pointer to the property string to be decoded.

StartNumberPtr (DD) Location for storing the returned starting number.

EndNumberPtr (DD) Location for storing the returned ending number.

BaseFlag (DD) Flag indicating which numeric base to use:

VDH_DP_DECIMAL Decimal

VDH_DP_HEX Hex

Return Codes

Success: If the function is successful, it returns a nonzero value and the ppProperty pointer is modified to point to the next range in the property string. StartNumberPtr and EndNumberPtr will have the range values. ppProperty is returned NULL after processing the last range.

Failure: If the function fails, it returns 0, indicating an invalid parameter. If BaseFlag contains an invalid value or if ppProperty is NULL, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: If a single value is found, EndNumberPtr is a -1. All the numbers are decoded in the specified base. A negative sign is used only as range delimiter. Numbers cannot have more than eight digits or a failure is returned. If this service returns Failure, it is still possible that the contents of StartNumberPtr or EndNumberPtr might have changed.

Because pointers passed are from a virtual device driver (not a user), there is no verification of addresses. Bad pointers result in page faults.

This function decodes the specified format of a property string as shown below:

String Syntax = "N1-N2,N3-N4,N5,N6-N7,..."

Notice that Nxare valid numbers in a specified base.

VDHDestroyBlockPool

Format

This function releases a memory block pool.

include mvdm.inc
EXTERN VDHDestroyBlockPool:NEAR
PoolHandle DD ?          ; Handle to the memory block pool to release
PUSH PoolHandle          ; Push PoolHandle
CALL VDHDestroyBlockPool ; Call the function

Parameters

PoolHandle (DD) Handle to the memory block pool to release.

Return Code

Success: If the function was successful, it returns nothing.

Failure: An invalid memory block pool handle causes a system halt to occur.

Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHDestroySel

Format

This function destroys a GDT selector created by VDHCreateSel.

include mvdm.inc
EXTERN VDHDestroySel:NEAR
GDTSelector DW ?   ; GDT selector to destroy
PUSH GDTSelector   ; Push GDTSelector
CALL VDHDestroySel ; Call the function

Parameters

GDTSelector (DW) GDT selector to be destroyed.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If GDTSelector was not created by VDHCreateSel, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: All selectors created with VDHCreateSel that map the terminating DOS session must be destroyed.

VDHDestroySem

Format

This function destroys a semaphore previously created with VDHCreateSem. The semaphore must be posted or unowned before calling this service.

include mvdm.inc
EXTERN VDHDestroySem:NEAR
SemHandle DD ?     ; Semaphore handle to destroy
PUSH SemHandle     ; Push SemHandle
CALL VDHDestroySem ; Call the function

Parameters

SemHandle (DD) Handle of the semaphore to destroy.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If SemHandle is invalid or if the semaphore is reset or owned, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHDevBeep

Format

This function performs the preempt beep request on behalf of the requesting virtual device driver.

include mvdm.inc
EXTERN VDHDevBeep:NEAR
Frequency DD ?  ; Frequency of the beep in hertz
Duration  DD ?  ; Duration of the beep in milliseconds
PUSH Frequency  ; Push Frequency
PUSH Duration   ; Push Duration
CALL VDHDevBeep ; Call the function

Parameters

Frequency (DD) Frequency of the beep in hertz.

Duration (DD) Duration of the beep in milliseconds.

Return Codes :Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0.

Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHDevIOCtl

Format

This function allows a virtual device driver to send device-specific commands to a physical device drivert hrough the generic IOCtl interface. The parameters and error return codes are identical to the ones found in the DosDevIOCtl API. Refer to the OS/2 Control Program Programming Reference for a complete description of each DosDevIOCtl API parameter.

include mvdm.inc
EXTERN VDHDevIOCtl:NEAR
DevHandle       DW ? ; Device handle returned by VDHOpen or VDHPhysicalDisk
Category        DD ? ; Category of function performed
Function        DD ? ; Function within category performed
ParmList        DD ? ; Pointer to command-specific input parameter area
ParmLengthMax   DD ? ; Maximum size of input parameter area, in bytes
ParmLengthInOut DD ? ; Pointer to length of the parameters passed, in bytes
DataArea        DD ? ; Pointer to the data area
DataLengthMax   DD ? ; Maximum size of the parameters passed, in bytes
DataLengthInOut DD ? ; Pointer to length of the parameters passed, in bytes
PUSH DevHandle       ; Push DevHandle
PUSH Category        ; Push Category
PUSH Function        ; Push Function
PUSH ParmList        ; Push ParmList
PUSH ParmLengthMax   ; Push ParmLengthMax
PUSH ParmLengthInOut ; Push ParmLengthInOut
PUSH DataArea        ; Push DataArea
PUSH DataLengthMax   ; Push DataLengthMax
PUSH DataLengthInOut ; Push DataLengthInOut
CALL VDHDevIOCtl     ; Call the function

Parameters

DevHandle (DW) Device handle returned by VDHOpen or VDHPhysicalDisk.

Category (DD) Category of function performed.

Function (DD) Function within category performed.

ParmList (DD) Pointer to the command-specific input parameter area.

ParmLengthMax (DD) Maximum size of the application input parameter area, in bytes. ParmLengthInOut can be longer than this on input, but not on output.

ParmLengthInOut (DD) Pointer to the length (in bytes) of the parameters passed by the caller in ParmList.

DataArea (DD) Pointer to the data area.

DataLengthMax (DD) Maximum size of the application data area, in bytes.

DataLengthInOut (DD) Pointer to the length (in bytes) of the parameters passed by the caller in ParmList. ParmLengthInOut can be longer than this on input, but not on output.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0. VDHGetError should be called to determine the nature of the problem. VDHGetError can return the following errors:

ERROR_INVALID_HANDLE

ERROR_INVALID_FUNCTION

ERROR_INVALID_CATEGORY

ERROR_INVALID_DRIVE

ERROR_INVALID_PARAMETER.

If the function is called when not at DOS session-task time, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Addresses (pointers) inside device-specific Data or Parameter Packets are not translated.

VDHDisarmTimerHook

Format

This function cancels a timer that was installed by VDHArmTimerHook before the handler was called.

include mvdm.inc
EXTERN VDHDisarmTimerHook:NEAR
TimerHook DD ?  ; Handle to the timer hook to disarm
PUSH TimerHook  ; Push TimerHook
CALL VDHDisarmTimerHook ; Call the function

Parameters

TimerHook (DD) Handle to the timer hook to disarm.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If TimerHook is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization, task, or interrupt context.

DOS Session Terminations: Any timer hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager at DOS session termination.

VDHEndUseVPMStack

Format

This function must be called once with every call made to VDHBeginUseVPMStack. It switches back to the original DOS session protected-mode stack when the use count goes to zero.

include mvdm.inc
EXTERN VDHEndUseVPMStack:NEAR
DD ?
PUSH ; Push
CALL VDHEndUseVPMStack ; Call the function

Parameters

(DD) None.

Return Codes

None.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: There must be a DPMI client running in the DOS session before calling this function.

VDHEnumerateVDMs

Format

This function is used to run a worker function for each DOS session in the system. The worker function can stop the enumeration by returning 0.

include mvdm.inc
EXTERN VDHEnumerateVDMs:NEAR
WorkerFcn DD ? ; Worker function
FcnData   DD ? ; Function-specific data to be passed each call
PUSH WorkerFcn ; Push WorkerFcn
PUSH FcnData   ; Push FcnData
CALL VDHEnumerateVDMs ; Call the function

Parameters

WorkerFcn (DD) Worker function, the routine that does the work.

The worker function uses the following interface:

EnumHook  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hVDM   - Handle to DOS session
;           [ESP + 4] - ulData - Function-specific data
;    EXIT   SUCCESS - Return a non-zero value in EAX, enumeration continues
;           FAILURE - Return 0 in EAX, stop enumeration

FcnData(DD) Function-specific data to be passed each call.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 indicating that a worker function stopped the enumeration.

Purpose

Context Issues: This function can be called in the task and interrupt context.

DOS Session Terminations

There are no DOS session termination implications for this function.

VDHExchangeMem

Format

This function exchanges the contents of two regions of linear address space. Overlapping regions are not supported.

include mvdm.inc
EXTERN VDHExchangeMem:NEAR
Source      DD ?    ; Source data address
Destination DD ?    ; Destination address
NumBytes    DD ?    ; Number of bytes to be exchanged
PUSH Source         ; Push Source
PUSH Destination    ; Push Destination
PUSH NumBytes       ; Push NumBytes
CALL VDHExchangeMem ; Call the function

Parameters

Source (DD) Address of the source data.

Destination (DD) Address of the target region.

NumBytes (DD) Number of bytes to exchange.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This function fails if the two memory regions to be exchanged overlap. Protection faults are handled as if a user application had performed the access. Therefore, writing to read-only pages or invalid page-table entries causes a virtual device driver page fault handler to gain control or causes the default behavior (that is, DOS session termination). This function also yields the CPU, if it is necessary to ensure that the thread dispatch latency limit is not exceeded.

VDHFindFreePages

Format

This function starts at a specified linear address and searches linear memory (up to a specified limit) for the largest free linear memory block. The address and size of the largest region found are returned.

include mvdm.inc
EXTERN VDHFindFreePages:NEAR
StartAddress DD ? ; Starting address
Pages        DD ? ; Size of the range (in pages)
PUSH StartAddress ; Push StartAddress
PUSH Pages        ; Push Pages
CALL VDHFindFreePages ; Call the function

Parameters

StartAddress (DD) Starting address of the linear memory range to be searched. Must be page-aligned and between 0 and 110000H (1MB+64KB).

Pages (DD) On input: The size of the linear memory range to search, in pages.

On output: The size of the region found, in pages.

Return Codes

Success: If the function is successful, it returns the address of the region found and sets Pages to the size of the region found (in pages).

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem.

Purpose

Context Issues: This function can be called in the initialization context where it searches only the global linear map. This function can also be called in DOS session-task context (DOS session creation only), where it searches only the DOS session's private linear map.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHFreeBlock

Format

This function releases a memory block previously allocated by VDHAllocBlock. The memory block is returned to the user's memory block pool for reuse.

include mvdm.inc
EXTERN VDHFreeBlock:NEAR
PoolHandle DD ? ; Handle to a memory block pool
BlockToFree  DD ? ; Address of the memory block to free
PUSH PoolHandle ; Push PoolHandle
PUSH BlockToFree ; Push BlockToFree
CALL VDHFreeBlock ; Call the function

Parameters

PoolHandle (DD) Handle (from VDHCreateBlockPool) to the pool of memory blocks that contains the memory block to free.

BlockToFree (DD) Address of the memory block to free.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If BlockPool is not a valid handle to a memory block pool, or if BlockToFree is not a block allocated from the BlockPool memory block pool, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: The only way to reclaim memory for freed blocks is to call VDHDestroyBlockPool.

VDHFreeDMABuffer

Format

This function frees a DMA buffer previously allocated by VDHAllocDMABuffer.

include mvdm.inc
EXTERN VDHFreeDMABuffer:NEAR
LinearAddress DD ? ; Starting linear address of the DMA buffer
PUSH LinearAddress ; Push LinearAddress
CALL VDHFreeDMABuffer ; Call the function

Parameters

LinearAddress (DD) Starting linear address of the DMA buffer.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If LinearAddress is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHFreeHook

Format

This function disarms and frees a hook.

include mvdm.inc
EXTERN VDHFreeHook:NEAR
HookHandle DD ?  ; Hook handle from VDHAllocHook
PUSH HookHandle  ; Push HookHandle
CALL VDHFreeHook ; Call the function

Parameters

HookHandle (DD) Hook handle (from VDHAllocHook) for the hook to free.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If HookHandle is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization or DOS session-task context.

DOS Session Terminations: Any context hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager.

VDHFreeMem

Format

This function frees memory that was previously allocated by VDHAllocMem.

include mvdm.inc
EXTERN VDHFreeMem:NEAR
MemAddress DD ? ; Address of the memory block to free
PUSH MemAddress ; Push MemAddress
CALL VDHFreeMem ; Call the function

Parameters

MemAddress (DD) Address of the memory block to be freed. Pointer is originally obtained from VDHAllocMem.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If MemAddress is not an address pointer allocated by VDHAllocMem, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHFreePages

Format

This function frees a memory object. All the memory associated with the memory object is released.

include mvdm.inc
EXTERN VDHFreePages:NEAR
ObjectAddress DD ? ; Address of the memory object to free
PUSH ObjectAddress ; Push ObjectAddress
CALL VDHFreePages  ; Call the function

Parameters

ObjectAddress (DD) Address of the memory object to free.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If ObjectAddress was not allocated by VDHAllocPages or VDHReallocPages, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization or task context. At initialization time, only global memory can be freed.

DOS Session Terminations: Any allocations made in the terminating DOS session's private area, or on behalf of the terminating DOS session, must be released by using VDHFreePages.

Notes: This function succeeds only if the linear range specified was allocated by a previous call to VDHAllocPages or VDHReallocPages. Freeing a memory region that was not allocated causes an internal error (a probable system halt).

If the region, starting at ObjectAddress, has been broken into two or more regions by calls to VDHMapPages, then VDHFreePages is not used.

VDHFreezeVDM

Format

This function freezes a DOS session, which prevents it from executing. The specified DOS session is notl alowed to execute any V86-mode code until VDHThawVDM is called. This freeze occurs when the specified DOS sessione laves kernel mode. The DOS session does not execute any V86-mode code from the time VDHFreezeVDM is called until the matching VDHThawVDM is called.

include mvdm.inc
EXTERN VDHFreezeVDM:NEAR
VDMHandle DD ?	; Handle to the DOS session to freeze
PUSH VDMHandle	; Push VDMHandle
CALL VDHFreezeVDM	; Call the function

Parameters

VDMHandle (DD) Handle to the DOS session to freeze.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If VDMHandle is not a valid DOS session handle, a system halt occurs.

Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: The DOS Session Manager thaws a frozen DOS session prior to calling any VDM_TERMINATE user hooks.

Notes: Each DOS session has a freeze count. This count starts at zero when the DOS session is created. Each VDHFreezeVDM call adds one to this count. Each VDHThawVDM call subtracts one from this count. The DOS session is frozen when the freeze count is 1 (one) or greater. The DOS session is thawed when the freeze count is 0 (zero). This allows multiple virtual device drivers to perform freeze and thaw operations without inadvertently causing the DOS session to run. If this count exceeds MAX_FREEZE_COUNT, VDHFreezeVDM returns VDHERR_FROZEN_LIMIT.

VDHGetCodePageFont

Format

This function returns the address of the code page font information, if code page support is active and a font is available for the given character cell dimensions.

include mvdm.inc
EXTERN VDHGetCodePageFont:NEAR
CellWidth DD ?	; Width of character cells, in pels
CellHeight DD ?	; Height of character cells, in pels
FontAddress DD ?	; Address where font table addresses will be copied
PUSH CellWidth	; Push CellWidth
PUSH CellHeight	; Push CellHeight
PUSH FontAddress	; Push FontAddress
CALL VDHGetCodePageFont	; Call the function

Parameters

CellWidth (DD) Width of character cells, measured in pels.

CellHeight (DD) Height of character cells, measured in pels.

FontAddress (DD) Address to which font table addresses will be copied.

Return Codes

Success: If the function is successful, it returns the size of the font table in bytes.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: If this function was called on behalf of the terminating DOS session, VDHReleaseCodePageFont must be called to release the fonts.

Notes: System memory can be allocated to hold the font, especially if it is a merged font (that is, merged from two separate font tables). When the virtual device driver is finished with the font, it must call VDHReleaseCodePageFont.

VDHGetDirtyPageInfo

Format

This function returns a bit vector for the dirty pages of a specified DOS session for a specified range of pages. The dirty bits for the range are reset.

include mvdm.inc
EXTERN VDHGetDirtyPageInfo:NEAR
VDMHandle DD ?	; Handle to the DOS session that owns the object
StartingAddress DD ?	; Address to start the scan
PageRange DD ?	; Range of pages to scan
PUSH VDMHandle	; Push VDMHandle
PUSH StartingAddress	; Push StartingAddress
PUSH PageRange	; Push PageRange
CALL VDHGetDirtyPageInfo	; Call the function

Parameters

VDMHandle (DD) Handle to the DOS session that owns the object. A 0 (zero) value indicates the current DOS session.

StartingAddress (DD) Starting address of the range of pages to scan.

PageRange (DD) Range (number of pages) to scan. Maximum allowed is 32.

Return Codes

Success: If the function is successful, it returns the bit vector. The low- order bit (that is, bit 0, the rightmost bit) is the dirty bit for the first page scanned. Bit 1 (from the right) is the dirty bit for the next page, and so forth for all the pages scanned.

Failure: If any of the input parameters are invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: The virtual dirty bits remain set until cleared by this function, regardless of the swapping activity that has occurred. The actual dirty bits in the page tables are reset whenever a page is swapped to the swap device and brought back into memory. This function is valid only for linear addresses up to 110000H (1MB+64KB) in a DOS session.

VDHGetError

Format

This function returns the error code from the last virtual DevHlp service called.

include mvdm.inc
EXTERN VDHGetError:NEAR
DD ?
PUSH	; Push
CALL VDHGet	; Call the function

Parameters

(DD) None.

Return Codes

Success: If the function is successful, it returns the error code.

Failure: If the function fails, it returns 0, indicating that the last virtual DevHlp call did not have an error.

Purpose

Context Issues: This function can be called in any context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: The return value is guaranteed to be valid as long as the virtual device driver does not block or yield between the virtual DevHlp service that failed and the call to VDHGetError. VDHGetError and VDHSetError work at hardware interrupt time. Each level of interrupt nesting (where task time is Level 0) has a separate error code variable.

VDHGetFlags

Format

This function gets the DOS session's EFlags Register.

include mvdm.inc
EXTERN VDHGetFlags:NEAR
ulFlagsAddr DD ?	; DOS session flag address.
PUSH ulFlagsAddr	; Push ulFlagsAddr
CALL VDHGetFlags	; Call the function

Parameters

ulFlagsAddr (DD) Address of the ULONG in which the EFLAGs value is to be returned.

Return Codes

None.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Virtual device drivers must use this interface instead of the client register frame pointer to change the DOS session's flags. Changes to the interrupt flag and the I/O Privilege Level (IOPL) field must be under the control of 8086 emulation so that VDHArmSTIHook works correctly.

Getting the Interrupt Flag (IF) must be under 8086 emulation control due to virtual mode extensions and DPMI.

VDHGetSelBase

Format

This function returns the base address for a Local Descriptor Table (LDT) selector.

include mvdm.inc
EXTERN VDHGetSelBase:NEAR
Selector DW ?	; LDT selector
pBasePointer DD ?	; Pointer for returned address
PUSH Selector	; Push Selector
PUSH pBasePointer	; Push pBasePointer
CALL VDHGetSelBase	; Call the function

Parameters :Selector (DW) LDT Selector.

pBasePointer (DD) Pointer for returned address.

Return Codes

Success: If the function is successful, it returns a nonzero value. The base address is returned in the variable pointed to by pBasePointer.

Failure: If the function fails, it returns 0 (zero).

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Error checking is performed only to ensure that the selector is allocated.

VDHGetVPMExcept

Format

This function gets the current value from the protected-mode exception table.

include mvdm.inc
EXTERN VDHGetVPMExcept:NEAR
Vector DD ?	; Exception vector number
pHandlerAddressPointer DD ?	; Pointer to put handler address
pFlag DD ?	; Pointer to a flag variable
PUSH Vector	; Push Vector
PUSH pHandlerAddressPointer	; Push pHandlerAddressPointer
PUSH pFlag	; Push pFlag
CALL VDHGetVPMExcept	; Call the function

Parameters

Vector (DD) Exception vector number (0-1FH).

pHandlerAddressPointer (DD) Pointer to put handler address.

pFlag (DD) Pointer to a flag variable for returning the flag value. Possible values are:

VPMXCPT32 A 32-bit handler was registered.

VPMXCPT_REFLECT The exception is reflected back to a V86-mode handler.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: There must be a DPMI client running in the DOS session before calling this function.

VDHGetVPMIntVector

Format

This function gets the application Ring 3 protected-mode interrupt handler. This service is used only for DOS Protected-Mode Interface (DPMI) support.

include mvdm.inc
EXTERN VDHGetVPMIntVector:NEAR
Vector DD ?	; Interrupt vector number
HandlerAddressPointer DD ?	; Pointer for return of handler address
PUSH Vector	; Push Vector
PUSH HandlerAddressPointer	; Push HandlerAddressPointer
CALL VDHGetVPMIntVector	; Call the function

Parameters Vector (DD) Interrupt vector number.

HandlerAddressPointer (DD) Pointer for return of the handler address.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Note: There must be a DPMI client in the DOS session before calling this function.

VDHHaltSystem

Format

This function causes a system halt.

include mvdm.inc
EXTERN VDHHaltSystem:NEAR
DD ?
PUSH	; Push
CALL VDHHaltSystem	; Call the function

Parameters

(DD) None.

Return Codes

None.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Calling VDHHaltSystem is an extremely drastic action. Calling VDHPopup and VDHKillVDM is the preferred method for handling a problem. VDHHaltSystem is used only if the virtual device driver is certain that the entire multiple DOS session environment is inoperable. In general, this function is used only by a base virtual device driver (for example, the virtual video device driver or virtual keyboard device driver), whose absence would render the multiple DOS session environment unusable. VDHPopup is called prior to VDHHaltSystem to tell the user what has happened.

VDHHandleFromPID

Format

This function returns the DOS session handle for a given Process ID.

include mvdm.inc
EXTERN VDHHandleFromPID:NEAR
ProcessID DW ?	; A DOS session process ID
PUSH ProcessID	; Push ProcessID
CALL VDHHandleFromPID	; Call the function

Parameters

ProcessID (DW) A DOS session Process ID.

Return Codes

Success: If the function is successful, it returns the DOS session handle for the Process ID.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHHandleFromSGID

Format

This function determines the DOS session handle given the Screen Group ID.

include mvdm.inc
EXTERN VDHHandleFromSGID:NEAR
ScreenGroupID DW ?	; Screen Group ID
PUSH ScreenGroupID	; Push ScreenGroupID
CALL VDHHandleFromSGID	; Call the function

Parameters

ScreenGroupID (DW) Screen Group ID.

Return Codes

Success: If the function is successful, it returns a handle to the DOS session that was given the Screen Group ID.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem.

Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHInstallFaultHook

Format

This function sets a page fault handler for a region of linear address space. The page fault handler receives control when a DOS session touches a page in a reserved region that was invalidated by VDHMapPages. The handler does not get control if the page was indicated "not present" by the Page Manager.

include mvdm.inc
EXTERN VDHInstallFaultHook:NEAR
VDMHandle DD ?	; DOS session handle; 0 = current DOS session
StartingAddress DD ?	; Starting linear address
Pages DD ?	; Number of pages
PageFaultHandlerFcnPtr DD ?	; Pagefault handler function
OptionFlag DD ?	; Options bit flag
PUSH VDMHandle	; Push VDMHandle
PUSH StartingAddress	; Push StartingAddress
PUSH Pages	; Push Pages
PUSH PageFaultHandlerFcnPtr	; Push PageFaultHandlerFcnPtr
PUSH OptionFlag	; Push OptionFlag
CALL VDHInstallFaultHook	; Call the function

Parameters

VDMHandle (DD) DOS session handle. If the parameter contains a 0 (zero), use the currently active DOS session.

StartingAddress (DD) Starting linear address.

Pages (DD) Number of pages.

PageFaultHandlerFcnPtr (DD) Page fault handler function.

The PageFaultHandlerFcnPtr function pointer contains the address of a function with the following interface:

PageFaultHandler  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pVDM - Address of the page in which fault occurred
;    EXIT   None
;
; CONTEXT   DOS session-task

OptionFlag(DD) Options bit flag.

Possible value:

VDHIFH_ADDR If set, pVDM is a byte-granular address. Otherwise, pVDM is a page-granular address.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If any of the input parameters are invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: Any fault hooks for the terminating DOS session must be released by using VDHRemoveFaultHook.

Notes: In order for the fault handler to terminate the DOS session, it must call VDHKillVDM and return. Page fault hooks are stored on a per-DOS session basis.

VDHInstallIntHook

Format

This function sets a handler for a V86 interrupt. The virtual device driver's interrupt handler gets control after any subsequently hooked DOS interrupt handlers.

include mvdm.inc
EXTERN VDHInstallIntHook:NEAR
Reserved DD ?	; Reserved ; must be set to 0
Vector DD ?	; Number of the interrupt vector to hook
HookFcn DD ?	; Address of the hook routine
OptionFlag DD ?	; Interface options flag
PUSH Reserved	; Push Reserved
PUSH Vector	; Push Vector
PUSH HookFcn	; Push HookFcn
PUSH OptionFlag	; Push OptionFlag
CALL VDHInstallIntHook	; Call the function

Parameters

Reserved (DD) Reserved. Must be set to 0.

Vector (DD) Number of the interrupt vector to hook (0-255).

HookFcn (DD) Address of the hook routine.

OptionFlag (DD) Interface options flag.

Possible values:

VDH_ASM_HOOK Use assembler language hook interface (for the assembler language interface refer to the function #VDHInstallIOHook). Otherwise, use the calling convention in the function prototype VDHENTRY found in the MVDM .INC include file, which is included with the Toolkit.

VDH_PRE_HOOK If set, install handler as a pre-reflection hook; that is, call the hook routine before reflecting the interrupt to V86 mode.

C Language Interface for the interrupt hook routine:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY   EBX - pcrf - Client register frame pointer
;     EXIT   If carry flag set, chain to next virtual device driver
;            If carry flag clear, don't chain to the next virtual
;            device driver
;     USES   EAX, ECX, EDX, FS, GS, Flags
;  CONTEXT   DOS Session-task

Return Codes

Success: If the function was successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If HookFcn is invalid or if Vector is out of range, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function. Interrupt hooks are automatically removed during DOS session termination.

Notes: The effect of this service is per-DOS session; the software interrupt handler must be installed as each DOS session is created. The return value from the interrupt hook controls whether the next virtual device driver is chained to or not. An explicit VDHPopInt is needed to remove the software interrupt (so that the ROM code is not executed).

VDHInstallIOHook

Format

This function is used to install I/O port hooks.

include mvdm.inc
EXTERN VDHInstallIOHook:NEAR
Reserved DD ?	; Reserved;must be set to 0
StartingPort DD ?	; Starting port number
NumPorts DD ?	; The number of ports from the starting point
IOPortHookEntry DD ?	; Pointer to I/O port hook entry
Flags DD ?	; Indicates interface and trapping options
PUSH Reserved	; Push Reserved
PUSH StartingPort	; Push StartingPort
PUSH NumPorts	; Push NumPorts
PUSH IOPortHookEntry	; Push IOPortHookEntry
PUSH Flags	; Push Flags
CALL VDHInstallIOHook	; Call the function

Parameters

Reserved (DD) Reserved. Must be set to 0 (zero).

StartingPort (DD) Number of the starting port.

NumPorts (DD) The number of ports from the starting port.

IOPortHookEntry (DD) Pointer to I/O port hook entry.

Flags(DD) Indicates interface and trapping options.

Possible values:

VDHIIH_ASM_HOOK Use assembler language hook interface (register-based). Otherwise, use a C hook interface (stack-based).

VDHIIH_ALWAYS_TRAP Always trap this range of addresses. The virtual device driver cannot call VDHSetIOHookState on any ports in the range.

VDHIIH_NO_SIMULATE Does not change WORD or other I/O handlers to simulation routines; allows WORD handlers for 1-port ranges.

VDHIIH_IGNORE Sets a system handler that does the following:

On WRITES: The OUT succeeds, but no actual I/O is performed.

On READS: The IN succeeds, and always returns -1 (all bits set to 1).

This is also the default behavior of unhooked ports. This behavior is compatible with the behavior of a machine when there is no hardware on a particular I/O address.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If IOPortHookEntry is invalid, or if StartingPort or NumPorts are out of range, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function. I/O hooks are automatically removed during DOS session termination.

Notes: This function installs I/O port trap handlers for a contiguous range of I/O addresses. Trapping is initially enabled for the specified ports. The I/O hook entry contains the handlers for each kind of I/O operation. If an entry in the table is NULL, that I/O type is simulated by using a lower I/O type (for example, WORD-I/O is simulated by performing two-byte I/O operations). I/O port hooks are kept on a per-DOS session basis; a virtual device driver generally installs I/O hooks at DOS session creation time.

VDHSetIOHookState can be used to enable or disable I/O trapping on a per- port, per-DOS session basis except when the VDHIIH_ALWAYS_TRAP option is specified. In this case, VDHSetIOHookState cannot be called on any port in the range for the current DOS session.

I/O hooks can take their parameters either from registers or the stack. High-performance hooks take register parameters (the I/O hook router is optimized for this case). Hooks with lower performance requirements take stack parameters, and therefore can be written in the C language.

WordInput, WordOutput and Other hooks can be NULL. In this case, the DOS Session Manager simulates these routines by using the ByteInput and ByteOutput routines. If the ByteInput or ByteOutput handlers are NULL, the DOS Session Manager uses default internal routines that do input and output to the hardware ports. This is most useful when a virtual device driver shadows the hardware state (by trapping OUT instructions) but does not care what is returned by IN instructions.

The client register frame (CRF) is updated as the instructions are simulated. For example, when the string I/O instructions are simulated, the client's EDI/ESI and ECX is incremented or decremented.

In a particular DOS session, a particular I/O port address can be hooked only by a single virtual device driver. If this function fails, no I/O hooks are installed.

The routing of I/O instructions to the supplied port hooks covers the specified range exactly. If an I/O instruction overlaps port address ranges hooked on separate VDHInstallIOHook calls, the instruction is simulated with smaller I/O operations to ensure that the hooks in each range are called correctly. For example, a virtual device driver that hooks 100H-103H , and installs a byte, WORD, and DWORD (other) handler would work as follows:

VDHInstallIOHook (reserved,0x100,4,&iohA,NULL);

The I/O instructions to each address with the length indicated cause the following hooks to be called:

Address	Length	Hooks Called
100	4	iohA.Other(100,DWORD)
101	4	iohA.Word(101) iohA.Byte(103)
102	4	iohA.Word(102)
103	4	iohA.Byte(103)

VDHRemoveIOHook must be called with identical StartingPort and NumPorts in order to remove these I/O hooks. Port hooks cannot be removed for a subset of the range of ports hooked on the call to VDHInstallIOHook. If the IOPortHookEntry is in instance data, the address passed to VDHInstallIOHook must be the same address passed to VDHRemoveIOHook or VDHSetIOHookState.

Virtual device drivers hook ports in all cases, even if the desired behavior is to act as though direct port access were allowed. This keeps the I/O Permissions Map small. Only a port that requires high performance (for example, a graphics card) is allowed to go straight through. The existence of such ports increases the size of the I/O Permissions Map in the Task State segment even if SetIOHookState is never called for them.

Interfaces for IOPortHookEntry are as follows:

ioh STRUC
   ioh_pbihByteInput    DD   ?
   ioh_pbohByteOutput   DD   ?
   ioh_pwihWordInput    DD   ?
   ioh_pwohWordOutput   DD   ?
   ioh_pothOther        DD   ?
ioh ENDS

ByteInput  PROC  NEAR
; PARAMETERS
;    ENTRY  - port - Port number
;           - pcrf - Client register frame pointer
;    EXIT   Data read returned in AL
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

ByteOutput  PROC  NEAR
; PARAMETERS
;    ENTRY  - bOutputData - Data to write
;           - port        - Port number
;           - pcrf        - Client register frame pointer
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

WordInput  PROC  NEAR
; PARAMETERS
;    ENTRY  - port - Port number
;           - pcrf - Client register frame pointer
;    EXIT   Data read returned in AX
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

WordOutput  PROC  NEAR
; PARAMETERS
;    ENTRY   - usOutputData - Data to write
;            - port         - Port number
;            - pcrf         - Client register frame pointer
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

OtherHook  PROC  NEAR
; PARAMETERS
;    ENTRY  EAX - ulOutputData         - Data for DWORD writes
;           [ESP + 16] - pulInputData  - Pointer to put input data
;                        (See NOTE, below)
;           EDX - port                 - Port number
;           ECX - flType               - I/O type
;               IO_TYPE_SHIFT          - Shift for type
;               IO_TYPE_MASK           - Mask for type
;               IO_TYPE_INPUT          - If set input else output
;               IO_TYPE_BYTE           - If set byte else WORD/DWORD
;               IO_TYPE_DWORD
;               IO_TYPE_STRING
;               IO_TYPE_REVERSE
;               IO_TYPE_ADDR32
;               IO_TYPE_REP
;               IO_SEG_SHIFT           - Shift for SEG  field
;               IO_SEG_MASK      - Mask for SEG field
;               IO_SEG_CS
;               IO_SEG_SS
;               IO_SEG_ES
;               IO_SEG_FS
;               IO_SEG_GS
;           EBX - pcrf           - Client register frame pointer
;    EXIT   If assembly language hook,
;              EAX - Data from DWORD reads
;              If carry flag set, simulate the I/O operation
;              If carry flag clear, I/O is done
;           If C hook
;              *pulInputData - Data from DWORD reads
;              If returns 0 in EAX, simulate the I/O operation
;              If returns a non-zero value in EAX, I/O is done
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task
; NOTES     The ASM OtherHook hook does not need the pulInputData parameter
;           because it returns DWORD input values in EAX, with the
;           carry flag used to indicate done/simulate.
;           The C hook has to use EAX to return status, and so needs the
;           additional parameter.

VDHInstallUserHook

Format

This function is used to set a handler for a specific DOS session event.

include mvdm.inc
EXTERN VDHInstallUserHook:NEAR
Event DD ?	; A DOS session event for which a handler is installed
UserHook DD ?	; User's handler for this event
PUSH Event	; Push Event
PUSH UserHook	; Push UserHook
CALL VDHInstallUserHook	; Call the function

Parameters

UserHook (DD) A user-defined handler for the event.

Event (DD) A DOS session event (such as DOS session termination).

Possible values are:

VDD_EXIT DOS session support is shutting down

VDM_CREATE DOS session creation

VDM_TERMINATE DOS session termination

VDM_FOREGROUND DOS session to the foreground

VDM_BACKGROUND DOS session to the background

VDM_CREATE_DONE DOS session creation completed successfully

VDM_VDD_CREATE_DONE DOS session virtual device driver creation completed

VDM_PDB_DESTROY DOS Program Data Block (PDB) destroyed in DOS session

VDM_PDB_CHANGE PDB changed in DOS session

VDM_CODEPAGE_CHANGE Code page change event

VDM_TITLE_CHANGE DOS session title change event

VDM_MEMORY_MAPPED_IN Pages mapped into a DOS session (0 to 1MB+64KB)

VDM_MEMORY_UN_MAPPED Pages unmapped from a DOS session (0 to 1MB+64KB).

VDM_BEGIN_VPM_TASK Protected-mode task has started

VDM_END_VPM_TASK Protected-mode task has ended

The interfaces for the UserHook handlers (depending on the event that is handled) are:

pfnCreate  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT   SUCCESS  Return a non-zero value
;           FAILURE  Return 0
;                    DOS session creation fails; the DOS Session Manager calls
;                    all the VDM_TERMINATE hooks for all virtual
;                    device drivers that returned SUCCESS on this
;                    DOS session creation.
;
;
; CONTEXT   DOS session-task

pfnTerminate  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session being terminated
;    EXIT   None
;
; CONTEXT   DOS session-task

pfnForeground  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session coming to the foreground
;    EXIT   None
;
; CONTEXT   Task

pfnBackground  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session going to the background
;    EXIT   None
;
; CONTEXT   Task

pfnExit  PROC  NEAR
; PARAMETERS
;    ENTRY  None
;    EXIT   None
;
; CONTEXT   Initialization and Task

pfnCreateDone  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT   None
;
; CONTEXT   DOS session creation

pfnVDDCreateDone  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT   None
;
; CONTEXT   DOS session Creation

pfnPDBDestroyed  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm    - Handle to DOS session
;           [ESP + 4] - segPDB  - V86 segment of terminating PDB
;    EXIT   None
;
; CONTEXT   DOS session-task

pfnPDBSwitched  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm   - Handle to DOS session
;           [ESP + 4] - segPDB - V86 segment of new PDB
;    EXIT   None
;
; CONTEXT   DOS session-task

pfnCodePageChanged  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - ulCodePage - New code page
;    EXIT   SUCCESS  Return a non-zero value in EAX
;           FAILURE  Return 0 in EAX
;                    An error is returned on the set code-page operation, but
;                    the rest of the device-code-page handlers are called.
;
; CONTEXT   DOS session-task

pfnVDMTitleChange  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pszTitle - new DOS session Title
;    EXIT   SUCCESS  Return a non-zero value in EAX
;           FAILURE  Return 0 in EAX
;
; CONTEXT   DOS session-task
; NOTES     1. This event is called for both full screen and windowed DOS session.
;           2. If pszTitle is NULL, the virtual device driver should treat it
;              as the DOS session's default and original title.
;           3. Ideally there should be only one virtual device driver for this
;              hook, but this is not a restriction.  One of the virtual device
;              drivers registered is responsible for putting the title.  Only
;              this virtual device driver returns a non-zero value, all others
;              return 0.

pfnMemoryMappedIn  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - hvdm   - Handle to DOS session
;           [ESP + 12] - page   - Page address
;           [ESP +  8] - cpages - Number of pages mapped in from
;                             the starting page address
;           [ESP +  4] - fl     - Type of mapping, (see VDHMapPages)
;    EXIT   SUCCESS  Return a non-zero value in EAX
;           FAILURE  Return 0 in EAX
;
; CONTEXT   DOS session-task

pfnMemoryUnMapped  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - hvdm   - Handle to DOS session
;           [ESP + 12] - page   - Page address
;           [ESP +  8] - cpages - Number of pages unmapped from
;                                                     the starting page address
;           [ESP +  4] - fl     - Type of mapping, (see VDHMapPages)
;    EXIT   SUCCESS  Return a non-zero value in EAX
;           FAILURE  Return 0 in EAX
;
; CONTEXT   DOS session-task

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure If the function fails, an invalid input parameter or a kernel heap overflow (that is, if the system runs out of memory) causes a system halt.

Purpose

Context Issues: This function can be called only in the initialization context.

DOS Sessions Terminations: The VDM_TERMINATE hook is called at DOS session termination. In the case of a partially created DOS session, the VDM_ TERMINATE handler is called only if all the registered VDM_CREATE handlers are called successfully. Partially created DOS sessions might occur when, for example, the Create_Handler for Virtual Device Driver A returned successfully, but the Create_Handler for Virtual Device Driver B failed. In this case, the Terminate_Handler for Virtual Device Driver A will not be called. This should be taken into consideration when deciding what to do in a Create_Handler and a Create_Done_Handler.

VDHIsVDMFrozen

Format

This function returns the freeze state of a DOS session.

include mvdm.inc
EXTERN VDHIsVDMFrozen:NEAR
VDMHandle DD ?	; Handle to the DOS session
PUSH VDMHandle	; Push VDMHandle
CALL VDHIsVDMFrozen	; Call the function

Parameters

VDMHandle (DD) Handle to the DOS session in question.

Return Codes

Success: If the DOS session is not frozen, the function returns 0 (zero). Otherwise, the function returns a nonzero value indicating the DOS session' s freeze count.

Failure: If VDMHandle is an invalid DOS session handle, a system halt occurs .

Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: See #VDHFreezeVDMfor a full discussion of freeze counting.

VDHKillVDM

Format

This function terminates the DOS session at the earliest opportunity. V86 code is no longer executed in the context of the terminated DOS session.

include mvdm.inc
EXTERN VDHKillVDM:NEAR
VDMHandle DD ?	; Handle to the DOS session to terminate
PUSH VDMHandle	; Push VDMHandle
CALL VDHKillVDM	; Call the function

Parameters

VDMHandle (DD) Handle to the DOS session to terminate. A value of 0 (zero) indicates the current DOS session.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If VDMHandle is not a valid DOS session handle, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: When a DOS session is terminating, all virtual device drivers that registered a VDM_TERMINATE hook by using VDHInstallUserHook are called.

Notes: This function sets a flag and returns. If the calling virtual device driver is in the context of the DOS session to be terminated, it must return to its caller in order for the termination to occur.

VDHLockMem

Format

This function verifies that a specified region is accessible in the requested manner, and locks the memory in the requested manner.

include mvdm.inc
EXTERN VDHLockMem:NEAR
StartingLinAddr DD ?	; Starting address of region in user process
NumBytes DD ?	; The size of the region to lock, in bytes.
OptionFlag DD ?	; Access option flags
PagelistArrayPtr DD ?	; Pointer to array of VDHPageList_s structures
ArrayCountPtr DD ?	; Points to count of VDHPageList_s elements
PUSH StartingLinAddr	; Push StartingLinAddr
PUSH NumBytes	; Push NumBytes
PUSH OptionFlag	; Push OptionFlag
PUSH PagelistArrayPtr	; Push PagelistArrayPtr
PUSH ArrayCountPtr	; Push ArrayCountPtr
CALL VDHLockMem	; Call the function

Parameters

StartingLinAddr (DD) Starting linear address of the region in the user process that is to be locked.

NumBytes (DD) Size in bytes of the region to lock.

OptionFlag (DD) Used to set access options for the locked region. The VDHLM _READ and VDHLM_WRITE flags are for verification purposes and are not mixed with the VDHLM_RESIDENT flag. Either the VDHLM_READ, VDHLM_WRITE, or VDHLM_ RESIDENT flag must be used. Note that VDHLM_RESIDENT cannot be combined with other flags.

Possible values are:

VDHLM_RESIDENT Lock physical pages.

VDHLM_READ Verify read access. VDHLM_READ is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.

VDHLM_WRITE Verify write access. VDHLM_WRITE is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.

VDHLM_CONTIGUOUS Force physical pages contiguous; can be used only for 64KB or less.

VDHLM_NOBLOCK Lock must not give up the CPU.

VDHLM_16M Must reside below the 16MB physical memory address.

PagelistArrayPtr (DD) Pointer to array of VDHPageList_s structures.

VDHLockMem fills this array. Each VDHPageList_s structure describes a single physically contiguous sub-area of the physical memory that was locked. If PagelistArrayPtr is set to VDHLM_NO_ADDR, no array is returned. The area that PagelistArrayPtr points to must contain enough VDHPageList_s structures to handle a worst case of one structure per page plus one more structure, that is, the region does not begin on a page boundary.

ArrayCountPtr (DD) Pointer to a variable where a count of the number of elements returned in the PagelistArrayPtr array is placed by VDHLockMem. If PagelistArrayPtris set to VDHLM_NO_ADDR, ArrayCountPtr is ignored.

Return Codes

Success: If the function is successful, it returns a lock handle. This is a global handle that can be used in any task context.

Failure If the function fails, it returns 0. If the function fails, call VDHGetError to determine the nature of the problem. If NumBytes equals 0, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function. There cannot be any memory locked on behalf of a particular DOS session.

Notes: The caller must call VDHUnlockMem to remove this lock. All locks are long-term. This function must be used prior to using any pointers passed to a virtual device driver from an OS/2 process (through DOSRequestVDD). This might also be useful to the callers of VDHCopyMem and VDHExchangeMem.

VDHMapPages, VDHReallocPages, and VDHFreePages will block if applied to pages that are locked. They unblock when the lock is released.

VDHMapPages

Format

This function maps a linear address region in the V86 address space.

include mvdm.inc
EXTERN VDHMapPages:NEAR
pvdhmsSourceRegion DD ?	; Pointer to source region definition
pvdhmtTargetRegion DD ?	; Target region definition
flMappingFlag DD ?	; Mapping options flag
PUSH pvdhmsSourceRegion	; Push pvdhmsSourceRegion
PUSH pvdhmtTargetRegion	; Push pvdhmtTargetRegion
PUSH flMappingFlag	; Push flMappingFlag
CALL VDHMapPages	; Call the function

Parameters

pvdhmsSourceRegion (DD) Pointer to VDHMAPSOURCE structure.

VDHMAPSOURCE is the source region definition for VDHMapPages with a data structure as follows:

VDHMapSource_s STRUC
vdhms_laddr	DD ?	; Source linear address of source memory object.
		; Source address to be mapped. Defines the
		; start of the source region for the mapping.
		; The region is the same length as the target region.
vdhms_hobj	DD ?	; Memory object handle set by the service to
		; hold a source handle for VDHMT_LINEAR
		; mappings. See the VDHMT_LINEAR description under MappingFlag.
VDHMapSource_s ENDS

pvdhmtTargetRegion (DD) Target region definition. Pointer to VDHMAPTARGET structure.

VDHMAPTARGET is the target region definition for VDHMapPages with a data structure as follows:

VDHMapTarget_s STRUC
vdhmt_laddr	DD ?	; Address in V86-space to be mapped
		; (0 <= vdhmt_laddr < 1MB+64KB)
vdhmt_cpg	DD ?	; Count of pages to map
vdhmt_hmap	DD ?	; Mapping handle. Must be zero on the first call to
		; VDHMapPages for region. Set by the service to
		; hold a handle used for remapping the region. The
		; handle is reset each time it is used. vdhmt_hmap
		; must be the value returned from the previous
		; VDHMapPages call for the region unless the pages
		; are either already invalid or else are being made
		; invalid. If either the old or new mapping is
		; invalid pages, vdhmt_hmap can be 0. Making a
		; region invalid restores pages in the region to
		; their reserved state, and sets vdhmt_hmap to 0.
VDHMapTarget_s ENDS

flMappingFlag(DD) Mapping options flag.

Possible values are:

VDHMT_INVALID Make target region pages invalid. vdhmt_hmap can be 0 (zero). This service is faster when the handle is provided, but virtual device drivers that do not store handles can map to invalid before remapping a region. Note that pvdhmsSourceRegion is ignored.

VDHMT_LINEAR Map linear source region into target region. vdhms_laddr contains the linear address to map at the start of the target region. This can only be a page-granular address in a memory allocation that was obtained by using VDHAllocPages or VDHReallocPages. After a successful mapping, the target region aliases the corresponding region of the source.

vdhms_hobj must be 0 (zero) the first time a newly allocated or reallocated source object is mapped. On a successful mapping, vdhms_hobj is filled in. Using this handle on the next mapping that uses the same source object speeds up that mapping call. Any linear address (laddr) at the start of the target region can be mapped using the handle. The returned result must be stored after each mapping call. Virtual device drivers can avoid storing this handle and always use 0 (zero), however, the call will be slower.

VDHMT_PHYSICAL Map physical source region into target region. vdhms_laddr contains the physical address to map at the start of the target region. vdhms_hobj is ignored.

VDHMT_BLACK_HOLE Map target region to black hole pages. pvdhmsSourceRegion is ignored.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem.

Purpose

This function maps a linear address region in the V86 address space to:

Part of a virtual memory object

Specific physical addresses (for physical devices)

Undefined memory (black holes)

Invalid pages (the unmapped state, which is the default state for reserved pages)

VDHMapPages also changes the virtual address contents of regions in the V86 address space (below 11000H (1MB+64KB)). Pages in this range can be made to address:

Part of a memory object previously allocated using VDHAllocPages or VDHReallocPages

Physical addresses for a device

Black hole (undefined memory) addresses that are read or written but do not retain their values

Invalid pages, which cause faults when accessed (see VDHInstallFaultHook)

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Mapping succeeds only if it completely replaces a previous mapping, or if the region contains only invalid pages. To change the size of a region, it must first be made invalid. The entire target region must lie below 11000H (1MB+64KB) and must be contained in pages previously reserved by VDHReservePages. VDHMapPages and VDHAllocPages can be used on the same target region but care must be taken. Before switching from one service to the other, the pages affected must first be made invalid. If pages are left invalid, a pagefault handler must be registered (through VDHInstallFaultHook) to handle page faults, in case the pages are accessed.

Both target and source addresses must be on page boundaries. If they are not, the page offset part of the address is ignored.

VDHOpen

Format

This function opens a file or device and returns a handle. The handle can be used with VDHRead, VDHWrite, VDHSeek, VDHClose, and VDHDevIOCtl. The parameters and error return codes are the same as those found in the DosOpen API. Refer to the OS/2 Control Program Programming Reference for a complete descriptions of each DosOpen API parameter.

include mvdm.inc
EXTERN VDHOpen:NEAR
FileName DD ?	; Pointer to the name of the file or device to open
FileHandle DD ?	; Where the system returns the file handle
ActionTaken DD ?	; Where a description of the action taken is returned
FileSize DD ?	; The new file's logical size (EOD) in bytes
FileAttribute DD ?	; File attribute bits used on file creation
OpenFLag DD ?	; Specifies action taken, based on whether file exists
OpenMode DD ?	; Describes the mode of the Open function
EABuf DD ?	; Address of a VDH_EAOP structure or NULL
PUSH FileName	; Push FileName
PUSH FileHandle	; Push FileHandle
PUSH ActionTaken	; Push ActionTaken
PUSH FileSize	; Push FileSize
PUSH FileAttribute	; Push FileAttribute
PUSH OpenFLag	; Push OpenFLag
PUSH OpenMode	; Push OpenMode
PUSH EABuf	; Push EABuf
CALL VDHOpen	; Call the function

Parameters

FileName (DD) Pointer to the ASCIIZ string containing the name of the device or file to open.

FileHandle (DD) Where the system returns the file handle.

ActionTaken (DD) Where the system returns a description of the action taken as a result of this function call.

FileSize (DD) The new file's logical size (EOD) in bytes.

FileAttribute (DD) File attribute bits used on file creation.

OpenFLag (DD) Specifies the action taken depending on whether the file exists.

Possible actions are:

VDHOPEN_FILE_EXISTED File existed

VDHOPEN_FILE_CREATED File created

VDHOPEN_FILE_TRUNCATED File replaced

OpenMode (DD) Describes the mode of the Open function.

EABuf (DD) Address of a VDH_EAOP structure, or NULL.

Return Codes

Success If the function is successful, it returns a nonzero value.

Failure If the function fails, it returns 0 (zero). If the function fails, VDHGetError should be called to determine the nature of the problem. VDHGetError can return the following errors:

ERROR_DISK_FULL

ERROR_OPEN_FAILED

ERROR_FILE_NOT_FOUND

ERROR_INVALID_PARAMETER

ERROR_PATH_NOT_FOUND

ERROR_ACCESS_DENIED

ERROR_DRIVE_LOCKED

ERROR_NOT_DOS_DISK

ERROR_SHARING_BUFFER_EXCEEDED

ERROR_SHARING_VIOLATION

ERROR_INVALID_ACCESS

ERROR_CANNOT_MAKE

ERROR_TOO_MANY_OPEN_FILES

ERROR_NOT_ENOUGH_MEMORY

If the function is called at other than DOS session-task time, or if the pszFileName pointer is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: Any handles the virtual device driver opened for the terminating DOS session must be closed with VDHClose.

Notes: Using VDHOpen does not interfere with the handle space available to the DOS session with INT 21H, except that it does count against the system-wide limit on the number of open file handles. These VDHOpen handles and the handles returned from INT 21H $Open cannot be used interchangeably.

VDHOpenPDD

Format

This function gets the address of the routine in a physical device driver that the virtual device driver uses to communicate with the physical device driver. The physical device driver's device must have previously registered its name and entry point using the DevHlp service RegisterPDD.

include mvdm.inc
EXTERN VDHOpenPDD:NEAR
DeviceName DD ?	; Pointer to device name of physical device driver to open
VDDEntryPoint DQ ?	; VDD entry point for VDD/PDD communication
PUSH DeviceName	; Push DeviceName
PUSH VDDEntryPoint	; Push VDDEntryPoint
CALL VDHOpenPDD	; Call the function

Parameters

DeviceName (DD) Pointer to the device name of the physical device driver to open.

VDDEntryPoint (DQ) Virtual device driver entry point for use by the physical device driver. Since physical device drivers are 16:16 modules, this is a 16:32 entry point.

The interface for the VDDEntryPoint:

EntryPoint  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 12] - ulFunc (DD) - Function code
;                        All function codes are private to a PDD/VDD pair.
;           [ESP +  8] - ul1 (DD)    - Function-specific
;                     If a pointer, it is 16:16, and will generally
;                        be an input packet.
;           [ESP +  4] - ul2 (DD)    - Function-specific
;                   If a pointer, it is 16:16, and will generally
;                        be an output packet.
;    EXIT  SUCCESS  Returns a non-zero value in EAX
;          FAILURE  Returns 0 in EAX

Return Codes

Success: If the function is successful, it returns a pointer to the physical device driver Inter-Device-Driver Communication (IDC) function. See " RegisterPDD" in the OS/2 Physical Device Driver Reference for a description of the physical device driver's IDC function.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem.

Purpose

Context Issues: This function can be called only in the initialization context.

DOS Session Terminations: The virtual device driver must communicate with the physical device driver to ensure that any resources the physical device driver has for the terminating DOS session are freed.

VDHOpenVDD

Format

This function returns a handle to a virtual device driver that can be used with VDHRequestVDD to enable a virtual device driver to communicate with another virtual device driver. The name must be one that was previously registered by using VDHRegisterVDD.

include mvdm.inc
EXTERN VDHOpenVDD:NEAR
VDDName DD ?	; Pointer to the name of the virtual device driver to open
PUSH VDDName	; Push VDDName
CALL VDHOpenVDD	; Call the function

Parameters

VDDName (DD) Pointer to a string containing the name of the virtual device driver to open.

Return Codes

Success: If the function is successful, it returns a handle to the virtual device driver.

Failure: If the function fails, it returns 0 (zero). This can occur if:

The virtual device driver referenced by VDDName is not found.

The virtual device driver was found, but has not registered a worker function (the routine that gets control when this interface is called) for virtual device driver/virtual device driver communication.

If this function is called with invalid parameters or in the incorrect context, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context, typically during DOS session creation.

DOS Session Terminations: The virtual device driver must communicate with the opened virtual device driver to ensure that any resources for the terminating DOS session are freed. In addition, the virtual device driver must communicate with any virtual device driver or OS/2 clients to ensure that any resources created due to the connection are freed. Notes: The recommended way for two virtual device drivers to rendezvous with this function is for each to attempt to open the other at the first creation of a DOS session. This allows the two virtual device drivers to work together regardless of the order in which they are initialized.

VDHOpenVIRQ

Format

This function returns an IRQ handle for use with the other Virtual Programmable Interrupt Controller (VPIC) services and, optionally, sets handlers called when an End Of Interrupt (EOI) or Interrupt Return (IRET) is executed during a simulated interrupt.

include mvdm.inc
EXTERN VDHOpenVIRQ:NEAR
IRQNumber DD ?	; Number of the IRQ to open
EOIHandler DD ?	; Address of End-Of-Interrupt (EOI) handler
IRETHandler DD ?	; Address of Interrupt Return (IRET) handler
Timeout DD ?	; IRET timeout value in milliseconds
OptionFlag DD ?	; Indicates whether the IRQ can be shared
PUSH IRQNumber	; Push IRQNumber
PUSH EOIHandler	; Push EOIHandler
PUSH IRETHandler	; Push IRETHandler
PUSH Timeout	; Push Timeout
PUSH OptionFlag	; Push OptionFlag
CALL VDHOpenVIRQ	; Call the function

Parameters

IRQNumber (DD) Number of the IRQ to open.

EOIHandler (DD) Address of End-Of-Interrupt (EOI) handler.

Linear address of the handler to be called when EOI is received by VPIC from a DOS session for the IRQ. If this is not desired, put a 0 (zero) in this parameter. Note that the IRQ is no longer "in service" (the ISR bit has been cleared) when the virtual device driver's EOI handler is called. The interface to the EOI handler is:

EOIHdlr  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

IRETHandler (DD) Address of Interrupt Return (IRET) handler.

Linear address of the handler to be called when the IRET in the DOS session 's interrupt code is executed for this IRQ. If this is not desired, set the parameter to 0 (zero). The interface for the IRET routine is:

IRETHdlr  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

Timeout (DD) IRET timeout value in milliseconds. When the timeout expires, the virtual device driver's IRET handler is called as if the IRET had occurred. A value of -1 indicates that no timeout occurs.

OptionFlag (DD) Option flag. Indicates whether the IRQ can be shared.

Possible value:

VPIC_SHARE_IRQ Indicates that the virtual device driver is willing to share the IRQ with another virtual device driver. All virtual device drivers that virtualize the same IRQ must pass this flag. Whether a particular IRQ is shared or unshared is determined by the setting of OptionFlagby the first virtual device driver to open the IRQ.

Return Codes

Success: If the function is successful, it returns an IRQ handle.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If IRQNumber, EOIHandler, IRETHandler, or OptionFlag are invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the initialization context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: A maximum of 32 virtual device drivers can share an IRQ.

VDHPhysicalDisk

Format

This function returns information about partitionable disks.

include mvdm.inc
EXTERN VDHPhysicalDisk:NEAR
Function DD ?	; Type of partitionable disks' information
DataPtr DD ?	; Pointer to the return buffer
DataLen DD ?	; Length of the return buffer
ParmPtr DD ?	; Pointer to the user-supplied information
ParmLen DD ?	; Length of the user-supplied information
PUSH Function	; Push Function
PUSH DataPtr	; Push DataPtr
PUSH DataLen	; Push DataLen
PUSH ParmPtr	; Push ParmPtr
PUSH ParmLen	; Push ParmLen
CALL VDHPhysicalDisk	; Call the function

Parameters

Function (DD) Type of partitionable disks' information to obtain.

Possible values are:

VDHPHYD_GET_DISKS Obtain the total number of partitionable disks

VDHPHYD_GET_HANDLE Obtain a handle to use with the Category 9 IOCtls

VDHPHYD_RELEASE_HANDLE Release a handle for a partitionable disk

DataPtr (DD) Pointer to the return buffer.

DataLen (DD) Length of the return buffer.

The returned data for each function is described as follows (all lengths are in bytes):

VDHPHYD_GET_DISKS Data Length=2. Total number of partitionable disks in the system. 1-based.

VDHPHYD_GET_HANDLE Data Length=2. Handle for the specified partitionable disk for Category 9 IOCtls.

VDHPHYD_RELEASE_HANDLE Data Length=0. None; pointer must be 0 (zero).

ParmPtr (DD) Pointer to the user-supplied information.

ParmLen (DD) Length of the user-supplied information (all lengths are in bytes):

VDHPHYD_GET_DISKS Parm Length=0. None; must be set to 0 (zero). 1-based.

VDHPHYD_GET_HANDLE Parm Length=string length. ASCIIZ string that specifies the partitionable disk.

VDHPHYD_RELEASE_HANDLE Parm Length=2. Handle obtained from VDHPHYD_GET_ HANDLE.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 (zero). VDHGetErrorshould be called to determine the nature of the problem. VDHGetErrorcan return the following error codes:

ERROR_ACCESS_DENIED

ERROR_INVALID_FUNCTION

ERROR_INVALID_HANDLE

ERROR_INVALID_PARAMETER

ERROR_LOCK_VIOLATION

If VDHPhysicalDisk is called in any context except DOS session task time, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: The handle obtained with Function Value=2 is released with Function Value=3. The ASCIIZ string used to specify the partitionable disk must be of the following format:

number:<null byte>
Where:
number	Specifies the partitionable disk (1-based) number in ASCII
:	Must be present
<null byte>	Specifies the byte of 0 for the ASCIIZ string

Notes: If the pointers passed by this function are allocated from the stack , then the SSToDS macro must be used to make the DS pointer relative. Addresses (pointers) inside device-specific data and parameter packets are not translated.

VDHPopInt

Format

This function reverses the effects of VDHPushInt. It removes the Interrupt Return (IRET) frame from the client's stack and restores the client's CS:IP to what was in the IRET frame.

include mvdm.inc
EXTERN VDHPopInt:NEAR
DD ?
PUSH	; Push
CALL VDHP	; Call the function

Parameters

(DD) None.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack overflow would occur. A stack exception will be simulated to the client.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This function always returns Successful when the DOS session is in client mode because no data accesses below 1MB can cause a fault.

VDHPopRegs

Format

This function reverses the VDHPushRegs by popping the specified client registers into the Client Register Frame (CRF) from the client's stack.

include mvdm.inc
EXTERN VDHPopRegs:NEAR
RegFlag DD ?	; Indicates which client registers to pop
PUSH RegFlag	; Push RegFlag
CALL VDHPopRegs	; Call the function

Parameters

RegFlag (DD) Flag indicating which client registers to pop.

These flags can be "ORed" together to indicate more than one register. Possible values are:

VDHREG_AX Pop the AX register

VDHREG_BX Pop the BX register

VDHREG_CX Pop the CX register

VDHREG_DX Pop the DX register

VDHREG_SI Pop the SI register

VDHREG_DI Pop the DI register

VDHREG_BP Pop the BP register

VDHREG_SP Pop the SP register

VDHREG_DS Pop the DS register

VDHREG_ES Pop the ES register

VDHREG_SS Pop the SS register

VDHREG_FLAG Pop the Flags register

VDHREG_ALL Pop all the registers

VDHREG_GENERAL Pop all the registers except SS and SP

Return Codes

Success: If the function was successful, it returns a nonzero value.

Failure: If this function fails, it returns 0 (zero) if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception is simulated to the client. If RegFlag is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: The caller should be careful to pass the same RegFlag value to VDHPopRegs that was used for the corresponding VDHPushRegs call. If the caller does not do this, the client stack can become damaged. This function always returns Successful when RegFlag is valid and the DOS session is in V86 mode because no data accesses below 1MB can cause a fault.

VDHPopStack

Format

This function pops the data off the client's stack.

include mvdm.inc
EXTERN VDHPopStack:NEAR
NumBytes DD ?	; Number of bytes to pop off the client's stack
DataPtr DD ?	; Pointer to data to pop off client's stack
PUSH NumBytes	; Push NumBytes
PUSH DataPtr	; Push DataPtr
CALL VDHPopStack	; Call the function

Parameters

NumBytes (DD) Number of bytes to pop off the client's stack. Must be an even number.

DataPtr (DD) Pointer to the data to pop off the client's stack.

Return Codes

Success: If the function was successful, it returns a nonzero value.

Failure: If this function fails, it returns 0 (zero) if a fault would occur when accessing the user stack. If NumBytes is odd, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This is a very low-level service. Appropriate care should be exercised in its use to ensure that the client's stack is not damaged. This service handles stack wraparound, and always returns successful when the DOS session is in V86-mode because no data accesses below 1MB can cause a fault.

VDHPopup

Format

This function displays a message according to the Message ID, and gets a response from the user.

include mvdm.inc
EXTERN VDHPopup:NEAR
ParmTable DD ?	; Pointer to a table of substitution strings
StrCount DD ?	; Number of substitution strings
MsgNumber DD ?	; Message number
RespPtr DD ?	; Pointer to a DD to receive the response
RespAllowed DD ?	; Bit field describing the allowed responses
Reserved DD ?	; Reserved;must be set to NULL
PUSH ParmTable	; Push ParmTable
PUSH StrCount	; Push StrCount
PUSH MsgNumber	; Push MsgNumber
PUSH RespPtr	; Push RespPtr
PUSH RespAllowed	; Push RespAllowed
PUSH Reserved	; Push Reserved
CALL VDHPopup	; Call the function

Parameters

ParmTable (DD) Pointer to a table of substitution strings.

StrCount (DD) Number of substitution strings.

MsgNumber (DD) Message number.

RespPtr (DD) Pointer to a DD to receive the returned response, filled on exit.

RespAllowed (DD) Bit field describing the allowed responses.

The allowed values are (any combination of these flags can be specified):

VDHP_FAIL (0001H)

VDHP_RETRY (0004H)

VDHP_IGNORE (0008H)

VDHP_TERMINATE_SESSION (0002H)

Reserved (DD) Reserved. Must be set to NULL.

Return Codes

Success: If the function is successful, it returns a nonzero value and the variable pointed to by RespPtr is filled in with actual response selected by the user.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem.

Purpose

Context Issues: This function can be called in the initialization context or the DOS session-task context. If it is called at initialization time, the message is displayed as a string on the console as if a DosWrite to standard output (stdout) had been made. No prompt is displayed, and no user response is returned. ResponsePtr is filled in with 0 (zero).

DOS Session Terminations: A DOS session cannot be terminated if it is waiting in this call for a user response.

Notes: This service is intended for virtual device drivers, which must inform the user of some extraordinary circumstance. For example, the virtual COM device driver (VCOM) issues this call to inform the user that a COM port is busy and gives the user a choice of how to handle the situation .

The input value of ResponsePtr is not used. "Retry" is the default action chosen for hard errors. If Retry is not allowed, "End the Program" is chosen as the default.

VDHPostEventSem

Format

This function posts an event semaphore. All the threads blocked on this semaphore will wake up.

include mvdm.inc
EXTERN VDHPostEventSem:NEAR
EventSemHandle DD ?	; Handle of an event semaphore
PUSH EventSemHandle	; Push EventSemHandle
CALL VDHPostEventSem	; Call the function

Parameters

EventSemHandle (DD) Handle of the event semaphore to post.

Return Codes

Success: If the function is successful, it will return nothing.

Failure: Posting a semaphore that is invalid or is already posted causes a system halt to occur.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHPrintClose

Format

This function is called by other virtual device drivers to flush and close a DOS session's open printers that have been opened for INT 17H printing. A DOS session can have more than one printer open. This service flushes and closes all of them.

include mvdm.inc
EXTERN VDHPrintClose:NEAR
VDMHandle DD ?	; DOS session handle
PUSH VDMHandle	; Push VDMHandle
CALL VDHPrintClose	; Call the function

Parameters

VDMHandle (DD) DOS session handle.

Return Codes

None.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: The system will flush and close any open printers when the DOS session is terminated.

Notes: If a printer has been left open because of direct access to the parallel ports, it will also be closed.

VDHPushFarCall

Format

This function simulates a Far Call to V86 code as if a DOS program had executed a Far Call instruction.

include mvdm.inc
EXTERN VDHPushFarCall:NEAR
SegOffAddr DQ ?	; Address of V86 mode or protected mode code to call
PUSH SegOffAddr	; Push SegOffAddr
CALL VDHPushFarCall	; Call the function

Parameters

SegOffAddr (DQ) The V86-mode segment:offset address of the V86-mode code to call, or selector:offset of protected-mode code to call.

Return Codes

Success: If the function was successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception is simulated to the client.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This function does not take effect until the operating system returns to the DOS session. In most cases, VDHArmReturnHook is called after this service. This allows the virtual device driver to regain control when the called V86 code executes its Far Return (RETF).

This function always returns successful when the DOS session is in V86 mode because no data accesses below 1MB can cause a fault.

VDHPushInt

Format

This function is used to change the DOS session's control flow to the interrupt handler when an interrupt is simulated. This function also simulates an interrupt to a specified V86-interrupt vector as if a DOS program has executed an INT n instruction. Any virtual device driver hooked on this interrupt with VDHInstallIntHook will get control as expected. The VDHArmReturnHook service can be used after this function is called to regain control when the V86 code executes the Interrupt Return (IRET).

If the DOS session is in V86-mode, the V86-mode handler from the IVT is called.

If the DOS session is in protected mode, the protected-mode interrupt handler is called.

include mvdm.inc
EXTERN VDHPushInt:NEAR
Vector DD ?	; Number of the interrupt vector to push
PUSH Vector	; Push Vector
CALL VDHPushIn	; Call the function

Parameters

Vector (DD) Number of the interrupt vector to push (0-255).

Return Codes

Success: If the function was successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If Vector is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This function does not take effect until the operating system returns to V86 mode. This function always returns successful when the DOS session is in V86 mode because no data accesses below 1MB can cause a fault .

VDHPushRegs

Format

This function pushes the specified client register from the Client Register Frame (CRF) to the client's stack. This service is usually used in conjunction with VDHPushFarCall to preserve user registers.

include mvdm.inc
EXTERN VDHPushRegs:NEAR
RegFlag DD ?	; Flag indicating which client registers to push
PUSH RegFlag	; Push RegFlag
CALL VDHPushRegs	; Call the function

Parameters

RegFlag (DD) Flag indicating which client registers to push. These flags can be ORed together to indicate more than one register.

Possible values are:

VDHREG_AX Push the AX register

VDHREG_BX Push the BX register

VDHREG_CX Push the CX register

VDHREG_DX Push the DX register

VDHREG_SI Push the SI register

VDHREG_DI Push the DI register

VDHREG_BP Push the BP register

VDHREG_SP Push the SP register

VDHREG_DS Push the DS register

VDHREG_ES Push the ES register

VDHREG_SS Push the SS register

VDHREG_FLAG Push the Flags register

VDHREG_ALL Push all the registers

VDHREG_GENERAL Push all the registers except SS and SP

Return Codes

Success: If the function was successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If RegFlagis invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Because the registers are saved on the DOS session stack (as opposed to a virtual device driver data structure), the virtual device driver is in no danger of losing track of data if the DOS session does not return to the virtual device driver. This service is used sparingly as it consumes DOS session stack space, and most DOS applications cannot tolerate excessive stack usage beyond their own needs.

This function always returns successful when RegFlag is valid and the DOS session is in V86 mode because no data accessed below 1MB can cause a fault .

VDHPushStack

Format

This function pushes data onto the client's stack .

include mvdm.inc
EXTERN VDHPushStack:NEAR
NumBytes DD ?	; Number of bytes to push on the client's stack
DataPtr DD ?	; Pointer to the data to push on the stack
PUSH NumBytes	; Push NumBytes
PUSH DataPtr	; Push DataPtr
CALL VDHPushStack	; Call the function

Parameters

NumBytes (DD) Number of bytes to push onto the client's stack. Must be an even number.

DataPtr (DD) A pointer to the data to be pushed.

Return Codes

Success: If the function was successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If NumBytes is odd, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This is a very low-level service. Appropriate care should be exercised in its use to ensure that the client's stack is not corrupted. This service handles stack wraparound, and always returns successful when the DOS session is in V86-mode because no data accesses below 1MB can cause a fault.

VDHPutSysValue

Format

This function sets a system value .

include mvdm.inc
EXTERN VDHPutSysValue:NEAR
Index DD ?	; Index of the system variable to set
Value DD ?	; New value for the system variable
PUSH Index	; Push Index
PUSH Value	; Push Value
CALL VDHPutSysVal	; Call the function

Parameters

Index (DD) Index of the system value to set. System value indexes are defined in VDMM.INC and listed in #VDHQuerySysValue.

Value (DD) New value for the system variable.

Return Codes

Success: If the function was successful, it returns nothing.

Failure: If Index is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization or DOS session-task (DOS session creation) context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This service is intended for system virtual device drivers to export system constants, such as ROM memory size. The behavior of the system is undefined if this service is used for any other purpose.

VDHQueryFreePages

Format

This function returns the total amount of free virtual memory in bytes. This is the amount of memory that could be allocated successfully.

include mvdm.inc
EXTERN VDHQueryFreePages:NEAR
DD ?
PUSH	; Push
CALL VDHQueryFree	; Call the function

Parameters

(DD) None.

Return Codes

Success: If the function is successful, it returns the number of bytes of free virtual memory.

Failure: If the function fails, it returns nothing.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This is a system-wide value that is not specific to the virtual address space of the DOS session.

VDHQueryHookData

Format

This function returns a pointer to the reference data created during the call to VDHAllocHook.

include mvdm.inc
EXTERN VDHQueryHookData:NEAR
HookHandle DD ?	; Hook handle from VDHAllocHook
PUSH HookHandle	; Push HookHandle
CALL VDHQueryHookData	; Call the function

Parameters

HookHandle (DD) Hook handle (from VDHAllocHook) for the hook to query.

Return Codes

Success: If the function is successful, it returns a pointer to the reference data block.

Failure: If HookHandle is invalid or if there is no reference data (that is, the RefDataSize parameter for VDHAllocHook is 0), a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization, task, or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHQueryLin

Format

This function converts a 16:16 (Far16) address to a 0:32 address. The 16:16 address can be a LDT-based or GDT-based address. The function is also callable on stack-based addresses.

include mvdm.inc
EXTERN VDHQueryLin:NEAR
Far16Addr DD ?	; 16:16 addressto be converted
PUSH Far16Addr	; Push Far16Addr
CALL VDHQueryLin	; Call the function

Parameters

Far16Addr (DD) The 16:16 address to be converted to a 0:32 address.

Return Code

Success: If the function is successful, it returns the 0:32 address that corresponds to Far16Addr.

Failure: If Far16Addr is an invalid selector, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization, task, or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This service does minimal checking on Far16Addr. The caller should make sure that Far16Addr is not invalid. If an invalid address is passed, this service can return an invalid address.

VDHQueryKeyShift

Format

This function is called by the virtual mouse device driver to query the keyboard shift state of a DOS session.

include mvdm.inc
EXTERN VDHQueryKeyShift:NEAR
VDMHandle DD ?	; DOS session handle
PUSH VDMHandle	; Push VDMHandle
CALL VDHQueryKeyShift	; Call the function

Parameters

VDMHandle (DD) DOS session handle.

Return Codes

Returns a USHORT which is a bitmask that indicates the current key state:

Right Shift 1

Left Shift 2

Ctrl 4

ALT 8

Left Ctrl 100

Left ALT 200

Right Ctrl 400

Right ALT 800

Purpose

Context Issues: This function can be called only in the interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHQueryProperty

Format

This function returns the current value of the specified DOS Setting.

include mvdm.inc
EXTERN VDHQueryProperty:NEAR
PropertyName DD ?	; Pointer to a property name
PUSH PropertyName	; Push PropertyName
CALL VDHQueryProperty	; Call the function

Parameters

PropertyName (DD) Pointer to an ASCIIZ string containing the property name for which information is being sought. Maximum length is 40 characters, including the terminating NULL.

Return Codes

Success: The format of the return value for successful depends on the type of the property being queried:

VDMP_BOOL The return value is a BOOL (Boolean). A 0 value represents FALSE and a nonzero value represents TRUE.

VDMP_INT The return value is a DD. It is guaranteed to be valid with respect to the bounding information specified in VDHRegisterVDD. Only the low half (DW) of the DD is significant. The high half is always 0.

VDMP_ENUM The return value is a pointer to a NULL-terminated string. The string is guaranteed to be one of those specified in VDHRegisterVDD.

VDMP_STRING The return value is a pointer to a NULL-terminated string. The string is guaranteed to be, at most, as long as the limit specified in VDHRegisterVDD.

VDMP_MLSTR The return value is a pointer to a NULL-terminated string. The string is guaranteed to be, at most, as long as the limit specified in VDHRegisterVDD.

Note: For property types VDMP_ENUM, VDMP_STRING, and VDMP_MLSTR, a pointer to the current value is returned to the virtual device driver, thereby avoiding a condition where an OS/2 process might be trying to change the same value. The virtual device driver calls VDHFreeMem to free the string after the virtual device driver is finished with it.

Failure: If the function fails, it returns NULL for property types VDMP_ENUM , VDMP_STRING, and VDMP_MLSTR, if there is insufficient memory to create a copy of the string value. In this case, the virtual device driver uses the default property value. NULL is also returned if pszName is invalid or is not a registered virtual device driver name.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: All memory allocated by a virtual device driver for use by the terminating DOS session is freed by using VDHFreeMem.

Notes: A virtual device driver can assume that the property value is valid. The system validates all types, except VDMP_STRING and VDMP_MLSTR, by using the validation values passed on the call to VDHRegisterProperty. The string types are validated by calling the virtual device driver function registered through VDHRegisterProperty.

VDHQuerySel

Format

This function returns the selector part of a 16:16 far pointer from a flat 0:32 address. The selector is in the Global Descriptor Table (GDT).

include mvdm.inc
EXTERN VDHQuerySel:NEAR
VirtAddress DD ?	; 0:32 virtual address
PUSH VirtAddress	; Push VirtAddress
CALL VDHQuerySel	; Call the function

Parameters

VirtAddress (DD) A 0:32 virtual address.

Return Codes

Success: If the function is successful, it returns a nonzero selector.

Failure: If the specified linear address is not in a virtual device driver data object, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization and task context:

During initialization time; query is allowed only on initialization and global data.

Global, instance, and stack data are allowed during task time (typically DOS session creation time), but initialization data is not.

DOS Session Terminations: Selectors for virtual device driver instance data are destroyed when the DOS session terminates. The virtual device driver must ensure that any physical device driver that was given this kind of selector is finished with it.

Notes: This function works only on 0:32 addresses in virtual device driver data objects and stacks. Each virtual device driver data object is limited to a maximum of 64KB in size so that the following formula can be used. A virtual device driver that needs more than 64KB of a particular class (INIT, global, or instance) must use multiple objects.

Notice that the selectors for virtual device driver data are created to map starting at a 64KB linear address boundary. As a result, VDHQuerySel needs to be called only once. The returned selector is valid for any memory in the particular object that contains the passed address, because the DOS Session Manager does not allow a virtual device driver data object to span a 64KB linear address boundary.

For virtual device driver instance data, this function returns a different GDT selector for each DOS session, and it can be called only in the context of a DOS session.

VDHQuerySem

Format

This function queries the state of an event or mutex semaphore.

include mvdm.inc
EXTERN VDHQuerySem:NEAR
SemHandle DD ?	; Handle to an event or mutex semaphore
SemStatePtr DD ?	; Pointer to a VDHSEMSTATE data area
PUSH SemHandle	; Push SemHandle
PUSH SemStatePtr	; Push SemStatePtr
CALL VDHQuerySem	; Call the function

Parameters

SemHandle (DD) Semaphore handle.

SemStatePtr (DD) A pointer to the data area to be filled with the state of the semaphore.

SemStatePtr points to a variable defined in VDMM.INC and structured as follows:

VDHSemState_s STRUC
        vss_SemType    DB   ?   ; VDH_EVENTSEM/VDH_MUTEXSEM
        vss_fOwned     DB   ?   ; 0 = Not Owned; 1 = Owned
        vss_fWaiter    DW   ?   ; 0 = No one waiting; 1 = Waiting
        vss_cRequest   DW   ?   ; Request count in mutex case
        vss_tid        DW   ?   ; TID of the owner, if owned
VDHSemState_s ENDS

Return Codes

None.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for state checking services.

Notes: The validity of SemStatePtr is not checked. The calling program must pass the address of a valid data area.

VDHQuerySysValue

Format

This function queries a system value.

include mvdm.inc
EXTERN VDHQuerySysValue:NEAR
VDMHandle DD ?	; Index of the system variable handle of the DOS session
Index DD ?	; Index values
PUSH VDMHandle	; Push VDMHandle
PUSH Index	; Push Index
CALL VDHQuerySysValue	; Call the function

Parameters

VDMHandle(DD) Index of the system variable handle of the DOS session to query. A value of 0 (zero) indicates the current DOS session.

Index(DD) VDHQuerySysValueindex values (as defined in VDMM.INC) and descriptions:

Global Values	Ordinal	Type	Units	Range
VDHGSV_DAY	0	DD	days	1 < = x < = 31
VDHGSV_MONTH	1	DD	months	1 < = x < = 12
VDHGSV_YEAR	2	DD	years	1980 < = x < = MAXULONG
VDHGSV_DAYOFWEEK	3	DD	days	0 < = x < = 6
VDHGSV_HOUR	4	DD	hours	0 < = x < = 24
VDHGSV_MINUTE	5	DD	minutes	0 < = x < = 60
VDHGSV_SECOND	6	DD	seconds	0 < = x < = 60
VDHGSV_HUNDREDTH	7	DD	1/100S	0 < = x < = 100
VDHGSV_SECONDS1970	8	DD	seconds	0 < = x < = MAXULONG
VDHGSV_TIMEZONE	9	DD	minutes	0 < = x < = MAXULONG
VDHGSV_MSECSBOOT	10	DD	milliseconds	0 < = x < = MAXULONG
VDHGSV_TIMERINTERVAL	11	DD	milliseconds	0 < = x < = 1000
VDHGSV_DYNVARIATION	12	DD		TRUE(nonzero)/FALSE(0)
VDHGSV_MAXWAIT	13	DD	seconds	0 < = x < = MAXULONG
VDHGSV_MINTIMESLICE	14	DD	milliseconds	0 < = x < = MAXULONG
VDHGSV_MAXTIMESLICE	15	DD	milliseconds	0 < = x < = MAXULONG

Global Values	Ordinal	Type	Units	Range
VDHGSV_YIELD	16	DD		TRUE(nonzero)/FALSE(0)
VDHGSV_TCYIELD	17	DD		TRUE(nonzero)/FALSE(0)
VDHGSV_VERMAJOR	18	DD		0 < = x < = MAXULONG
VDHGSV_VERMINOR	19	DD		0 < = x < = MAXULONG
VDHGSV_VERREVISION	20	DD		0 < = x < = 255
VDHGSV_MACHINETYPE	21	DD		MACHINE_TYPE_
VDHGSV_BLACKHOLEADDR	22	DD	bytes	0 < = x < = MAXULONG
VDHGSV_BLACKHOLESIZE	23	DD	bytes	0 < = x < = MAXULONG
VDHGSV_FGNDSESSIONID	24	DD		0 < = x < = MAXSESSIONS
VDHGSV_ARPLADDR	29	DD
VDHGSV_MACHINEINFO	30	DD		Pointer to System Configuration table
VDHGSV_PPOSREGS	31	DD		Pointer to POS Regs structure
VDHGSV_PICMASK	32	DD		Original PIC mask values

Local Values	Ordinal	Type	Units	Range
VDHLSV_HVDM	4096	DD
VDHLSV_PID	4097	DD
VDHLSV_PCRF	4098	DD
VDHLSV_SESSIONID	4099	DD		N < = x < MAXSESSIONS
VDHLSV_FOREGROUND	4100	DD		TRUE(nonzero)/FALSE(0)
VDHLSV_RMSIZE	4101	DD	KB	0 < x < = 640
VDHLSV_CODEPAGEID	4102	DD		See DosGetCP
VDHLSV_PRIORITYCLASS	4103	DD		See VDHSetPriority
VDHLSV_PRIORITYLEVEL	4104	DD		See VDHSetPriority
VDHLSV_VPICBASE	4105	DD

Return Code

Success: If the function is successful, it returns the value of the system variable. If the value is 0 and VDHGetError returns 0, then 0 is the correct value.

Failure

If VDMHandle or Index is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in any context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Systems values are of two classes, global and per-DOS session. These classes are distinguished by the prefix of the index name. Variables with prefixes of VDHGSV_ are global. Variables with a VDHLSV_ prefix are per-DOS session.

VDHQueryVIRQ

Format

This function returns information about the virtual mask, interrupt request flag, interrupt in-service flag , and pending virtual device driver Interrupt Return (IRET) handlers for the specified IRQ, device, or DOS session.

include mvdm.inc
EXTERN VDHQueryVIRQ:NEAR
VDMHandle DD ?	; IRQ handle from DOS session handle
IRQHandle DD ?	; IRQ handle from VDHOpenVIRQ
PUSH VDMHandle	; Push VDMHandle
PUSH IRQHandle	; Push IRQHandle
CALL VDHQueryVIRQ	; Call the function

Parameters

VDMHandle (DD) IRQ handle from VDHOpenVIRQ DOS session handle. A value of 0 (zero) indicates the current DOS session.

IRQHandle (DD) IRQ handle from VDHOpenVIRQ.

Return Code

Success: If the function is successful, it returns the IRQ status as a DD of flag bits:

VPICQ_REQUEST_PENDING Request is pending for the queried IRQ

VPICQ_IN_SERVICE Queried IRQ is in service

VPICQ_VIRT_MASK Mask is turned ON for the queried IRQ

VPICQ_STAT_IRET_PENDING IRET is pending for the queried IRQ.

Failure: If VDMHandle or IRQHandle is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHRaiseException

Format

This function is used to raise an exception, which is reflected to a DOS session as if the exception were caused by the hardware.

include mvdm.inc
EXTERN VDHRaiseException:NEAR
Exception DD ?	; An exception number
ErrorCode DD ?	; Error code for the exception
ExtraCode DD ?	; Extra error code
PUSH Exception	; Push Exception
PUSH ErrorCode	; Push ErrorCode
PUSH ExtraCode	; Push ExtraCode
CALL VDHRaiseException	; Call the function

Parameters

Exception (DD) An exception number that might be caused by the 80386 microprocessor.

ErrorCode (DD) Error code for the exception defined for the 80386 microprocessor.

ExtraCode (DD) Extra error code for DPMI 1.0 page faults.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 (zero).

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHRead

Format

This function reads bytes from a file or device previously opened by VDHOpen.

include mvdm.inc
EXTERN VDHRead:NEAR
FileHandle DW ?	; Handle to the file or device to read
ReadBufferPtr DD ?	; Address of the buffer to store the bytes read
NumBytes DD ?	; Number of bytes to read
PUSH FileHandle	; Push FileHandle
PUSH ReadBufferPtr	; Push ReadBufferPtr
PUSH NumBytes	; Push NumBytes
CALL VDHRead	; Call the function

Parameters

FileHandle (DW) Handle to the file or device to read.

ReadBufferPtr (DD) Address of the buffer to store the bytes read.

NumBytes (DD) Number of bytes to read.

Return Codes

Success: If the function is successful, it returns a count of the number of bytes read; this can be equal to 0 (zero).

Failure: If the function fails, it returns 0FFFFFFFFH. VDHGetError should be called to determine the nature of the problem. If FileHandle is invalid or this function is called in any context except DOS session-task, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHReadUBuf

Format

This function is used to read from protected-mode address space as if the read were done at Ring 3. This means any other faults are trapped. All faults are passed on to the DOS session application handler through VDHRaiseException.

include mvdm.inc
EXTERN VDHReadUBuf:NEAR
DestBuffer DD ?	; Destination buffer for copy.
ByteCount DD ?	; Count of bytes
Selector DW ?	; Application selector
OffsetPointer DD ?	; Address of the variable containing the offset
Flag DD ?	; Checking controls flag
PUSH DestBuffer	; Push DestBuffer
PUSH ByteCount	; Push ByteCount
PUSH Selector	; Push Selector
PUSH OffsetPointer	; Push OffsetPointer
PUSH Flag	; Push Flag
CALL VDHReadUBuf	; Call the function

Parameters

DestBuffer (DD) Destination buffer for copy.

ByteCount (DD) Count of bytes.

Selector (DW) Application selector.

OffsetPointer (DD) Address of the variable containing the offset for the start of the read.

Flag(DD) Flag containing checking controls.

Possible values are:

VPM_PROT_READ Check for read.

VPM_PROT_WRITE Check for write.

VPM_FAULT_IF_SU_SET Fault, if supervisor pages.

VPM_FAULT_IF_RO Fault, if writing to read-only descriptor.

VPM_SEL_PRESENT Caller knows descriptor is present.

VPM_SEL_WRITEABLE Caller knows descriptor is writable.

VPM_SEL_IS_SS Selector is client's stack.

VPM_XCPTRET_ALT After exception, return to alternate mode. For example, if the client was in protected mode when the service was called, return in V86 mode after the exception is handled.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 if a bad address reference is causing the fault. In this case, OffsetPointer is updated with the address of the fault. For selector faults, OffsetPointer is unchanged.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: If the routine fails, the caller must clean up and exit so that the exception can be simulated to the user. Supervisor pages can be read without faults to avoid the overhead of checking.

VDHReallocPages

Format

This function expands or shrinks a memory object.

include mvdm.inc
EXTERN VDHReallocPages:NEAR
ObjectAddress DD ?	; Address of the memory object to resize
NumPages DD ?	; New size of the memory object (in 4KB pages)
Reserved DD ?	; Must be zero
PUSH ObjectAddress	; Push ObjectAddress
PUSH NumPages	; Push NumPages
PUSH Reserved	; Push Reserved
CALL VDHReallocPages	; Call the function

Parameters

ObjectAddress (DD) Address of the memory object to reallocate or resize.

NumPages (DD) The new size of the memory object (in 4KB pages).

Reserved (DD) Must be set to zero.

Return Codes

Success: If the function is successful, it returns that address of the reallocated memory block.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If the memory object at ObjectAddress was not allocated by VDHAllocPages or VDHReallocPages, or if the NumPages or Reserved parameters are invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: Any allocations that are not in the terminating DOS session's private area must be released by using VDHFreePages.

Notes: When an allocation made with VDHAllocPages is shrunk by VDHReallocPages, the linear range between the end of the allocation and the original end of the allocation remains available for object growth without movement. If the linear range encompassed by the new size was reserved (with VDHReservePages), reallocation occurs without movement. Reallocation also succeeds without movement if the object was larger than the desired size since it last moved. Regardless of VDHReallocPages activity, all pages in the allocation retain the same properties, that is, fixed, system, and physical.

VDHRegisterAPI

Format

This function is used to register a virtual device driver's API handler that can be called by a DOS or DPMI application in the DOS session. A V86-mode or protected-mode (or both) API handler is set for a particular virtual device driver. Each virtual device driver must register with a unique virtual device driver name. This service provides a mechanism for DOS applications to communicate directly with the virtual device driver.

include mvdm.inc
EXTERN VDHRegisterAPI:NEAR
VDDName DD ?	; Pointer to the name of the virtual device driver
pfnV86Hook DD ?	; V86-mode hook routine address
pfnVPMHook DD ?	; VPM-mode hook routine address
PUSH VDDName	; Push VDDName
PUSH pfnV86Hook	; Push pfnV86Hook
PUSH pfnVPMHook	; Push pfnVPMHook
CALL VDHRegisterAPI	; Call the function

Parameters

VDDName (DD) Pointer to the name of the virtual device driver. Maximum length is MAXLENXDD.

pfnV86Hook (DD) V86-mode hook routine address (NULL if no V86-mode handler is needed).

pfnVPMHook (DD) VPM-mode hook routine address (NULL if no VPM-mode handler is needed).

Return Codes

Success: Returns TRUE

Failure: Returns FALSE

Purpose

Context Issues: This function can only be called in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function. The hook(s) are freed when the DOS session is terminated .

Notes:

Hook routine:

HookRoutine PROC NEAR
; PARAMETERS
; ENTRY    [ESP + 8] - p - reserved
;             [ESP + 4] - pcrf - pointer
;           to client register frame
; EXIT     None
; CONTEXT  DOS session-task

DOS or DPMI applications issue the following INT 2F calls to determine if they are running under OS/2, and then get the virtual device driver API entry point.

Get OS/2 version (DOS or DPMI applications can use this INT 2F call to get the OS/2 version):

     ENTRY     AX = 0x4010
     EXIT      If OS/2 is running:
                  AX = 0
                  BX = OS/2 version (example:BX = 1400 for 2.0)
               If OS/2 is not present, AX is unchanged

Get virtual device driver API entry points. DOS or DPMI applications can use this INT 2F call to get the address to call the virtual device driver entry points. If the INT 2F is issued in V86 mode, an address that calls the V86 virtual device driver API handler is returned. If the INT 2F call is issued in protected-mode, an address that corresponds to the protected- mode API handler is returned.

     ENTRY     AX = 0x4011
               DS:(E)SI = pointer to ASCIIZ name registered
                              with VDHRegisterAPI
     EXIT      If VDD API handler exists:
                  ES:DI = address to call to invoke handler
               If handler is not registered:
                  ES:DI = NULL

The DOS or DPMI application can then issue a far call to the address returned to invoke the virtual device driver API handler.

VDHRegisterDMAChannel

Format

This function is used by virtual device drivers to register with the virtual DMA device driver (VDMA) to get the ownership of a DMA channel.

include mvdm.inc
EXTERN VDHRegisterDMAChannel:NEAR
DMAChannel DD ?	; DMA channel
DMAHandlerFunc DD ?	; The virtual device driver's DMA-handling routine
PUSH DMAChannel	; Push DMAChannel
PUSH DMAHandlerFunc	; Push DMAHandlerFunc
CALL VDHRegisterDMAChannel	; Call the function

Parameters

DMAChannel (DD) DMA channel.

DMAHandlerFunc( DD) The virtual device driver's DMA-handler function.

The interface for the DMA-handler routine is as follows:

DMAHandler  PROC  NEAR
; PARAMETERS
; ENTRY  [ESP + 8] - hvdm   - DOS session requesting DMA
;           [ESP + 4] - iEvent - VDD_DMA_MASKOFF (Start DMA, Event)
;                                VDD_DMA_MASK    (Stop  DMA, Event)
; EXIT   SUCCESS - Returns nonzero in EAX
;                     If VDD_DMA_MASKOFF,
;                        the virtual DMA device driver will program the DMA
;                     If VDD_DMA_MASK, don't care
;           FAILURE - Returns 0 (zero) in EAX

Return Codes

Success: If the function is successful, it returns 1.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem.

Purpose

Context Issues: This function can be called only in the initialization context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: In the case of VDD_DMA_MASKOFF, the virtual device driver gets the hardware ownership and unhooks all the ports. If hardware ownership is not available immediately, it blocks the DOS session. On VDD_DMA_MASK, the virtual device driver returns the ownership and hooks back the ports.

If the DOS application programs the hardware handled by a virtual device driver first, and then programs the DMA, this virtual device driver receives ownership of hardware, unhooks all ports on first port access, and arms a timer for a safe period. This is a preventive measure to protect the system from errant I/O to DMA ports. If the timer fires, the virtual device driver releases the hardware. In this case, the virtual device driver does nothing when the virtual DMA device driver later calls with VDD_DMA_MASKOFF .

It is the virtual device driver's responsibility (in DMAHandlerFunc) to handle the unavailability of hardware ownership. This means the virtual device driver must put up the pop-up and suspend (or terminate) the DOS session. The virtual device driver passes the interrupt notification to the virtual DMA device driver before simulating that interrupt to the DOS session, if it owns the hardware.

In between VDD_DMA_MASKOFF and VDD_DMA_MASK events, the virtual DMA device driver always returns the physical DMA state, if the application polls its status or transfer count. This is appropriate because the virtual device driver owns the device during this period. VDD_DMA_MASK event notification takes place before actually masking the register in DMA. VDD_DMA_MASKOFF takes place after masking off the DMA.

DMA Channel 4 is not supported.

VDHRegisterProperty

Format

This function registers a virtual device driver property with the DOS Session Manager.

include mvdm.inc
EXTERN VDHRegisterProperty:NEAR
PropertyName DD ?	; Property name pointer
Reserved DD ?	; Must be set to 0
Reserved DD ?	; Must be set to 0
PropertyType DW ?	; Property type
PropertyOrdinal DW ?	; Property ordinal
PropertyFlag DD ?	; Property flag
DefaultValue DD ?	; Default value of the property
ValidationData DD ?	; Validation data
ValidationFunc DD ?	; Pointer to a virtual device driver property function
PUSH PropertyName	; Push PropertyName
PUSH Reserved	; Push Reserved
PUSH Reserved	; Push Reserved
PUSH PropertyType	; Push PropertyType
PUSH PropertyOrdinal	; Push PropertyOrdinal
PUSH PropertyFlag	; Push PropertyFlag
PUSH DefaultValue	; Push DefaultValue
PUSH ValidationData	; Push ValidationData
PUSH ValidationFunc	; Push ValidationFunc
CALL VDHRegisterProperty	; Call the function

Parameters

PropertyName (DD) Pointer to an ASCIIZ string containing the property name. Maximum length is 40 characters.

Reserved (DD) Must be set to 0 (zero).

Reserved (DD) Must be set to 0 (zero).

PropertyType (DW) Property type.

Values are:

VDMP_BOOL 0-Boolean

VDMP_INT 1-Integer. DD size, but only DW is valid

VDMP_ENUM 2-Enumeration

VDMP_STRING 3-ASCIIZ string

VDMP_MLSTR 4-Multi-line string, separated by linefeed (0AH)

PropertyOrdinal (DW) Property ordinal.

Values are:

VDMP_ORD_OTHER 0-Custom virtual device driver property

VDMP_ORD_KERNEL 1-ASCIIZ path of DOS kernel

VDMP_ORD_SHELL 2-ASCIIZ path of DOS_SHELL

VDMP_ORD_RMSIZE 3-Integer size of DOS box (128KB-640KB)

VDMP_ORD_FCB 4-Integer total FCBs

VDMP_ORD_FCB2 5-Integer FCBs immune to close LRUing

VDMP_ORD_BREAK 6-Boolean Break flag

VDMP_ORD_DOSDD 7-Multi-line string DOS_DEVICE

VDMP_ORD_VMBOOT 8-ASCIIZ string virtual machine boot drives

VDMP_ORD_VERSION 10-Multi-line string fake version entries

VDMP_ORD_DOS_UMB 11-Boolean flag. DOS_UMB

VDMP_ORD_DOS_HIGH 12-Boolean flag. DOS_HIGH

VDMP_ORD_LASTDRIVE 13-ASCIIZ DOS_LASTDRIVE

VDMP_ORD_FILES 14-Integer total FILES

PropertyFlag (DD) Property flag.

Possible value:

VDMP_CREATE Property can be specified only at DOS session creation. Any change to the property after DOS session creation is ignored.

DefaultValue (DD) Default value of the property.

The format of this field depends on the value of PropertyType:

VDMP_BOOL DefaultValue is interpreted as a BOOL (Boolean) value.

VDMP_INT DefaultValue is interpreted as a DD value. Only the low half is used (the high half is ignored) so this is more similar to a DW than a DD.

VDMP_ENUM DefaultValue is interpreted as a pointer to an ASCIIZ string.

VDMP_STRING DefaultValue is interpreted as a pointer to an ASCIIZ string.

VDMP_MLSTR DefaultValue is interpreted as a pointer to an ASCIIZ string.

ValidationData(DD) Validation data.

The value of this field depends on the value of PropertyType.

VDMP_BOOL ValidationData is NULL. The user is expected to validate Booleans .

VDMP_INT ValidationData is a pointer to a VPBOUND structure:

VPBOUND Limits for VDMP_INT properties. Note that maximum > minimum must hold, the range of maximum to minimum must be a multiple of step, and step= 1 implies that all values between minimum and maximum are valid:

VPBOUND_s STRUC
   min  DW   ?   ; minimum allowed value
   max    DW   ?   ; maximum allowed value
   step   DW   ?   ; increment between values
VPBOUND_s ENDS

VDMP_ENUM ValidationData is a pointer to a set of ASCIIZ strings terminated by a zero byte, which is the allowed set of responses. The Shell uses this to construct a list or combination box for the user to pick from. Empty ("\ 0") strings are not allowed.

VDMP_STRING ValidationData is a DD that is the maximum allowed string length (including the NULL terminator).

VDMP_MLSTR ValidationData is a DD that is the maximum allowed string length (including the NULL terminator).

ValidationFunc(DD) Function that validates and accepts changes to this property for a running DOS session. Ignored if VDMP_CREATE is specified in conjunction with VDMP_BOOL, VDMP_INT, or VDMP_ENUM.

The interface for the ValidationFunc is defined as follows:

VDHPROP_VALIDATE  EQU  0x00000000L
VDHPROP_SET       EQU  0x00000001L

ValidationFunc  PROC  NEAR
; PARAMETERS
; ENTRY  [ESP + 16] - op (DD)
;           [ESP + 12] - hvdm (DD)
;           [ESP +  8] - cb (DD)
;           [ESP +  4] - pch (DD)

PFNVDHRP is a pointer to a property function of the virtual device driver that performs property setting and validation. This routine is required for any property that does not specify VDMP_CREATE. Set operations can be requested any time after a DOS session is created. The validation operation can be requested at any time, even before a DOS session is created. Validation is requested only for VDMP_STRING and VDMP_ MLSTR types because all other types can be validated using the information supplied by VDHRegisterProperty.

Parameter	Data Type	Description
op	DD	Operation to perform. See the following parameter.
hvdm	DD	Handle of DOS session. Undefined if op = VDHPROP_VALIDATE.
cb	DD	Count of bytes pointed by pch. See the following parameter.
pch	DD	Pointer to the value set or validate. See the following parameter.

op Operation to perform (enumeration):

VDHPROP_VALIDATE Validate property for any process. Only called for VDMP_ STRING and VDMP_MLSTR properties.

VDHPROP_SET Set an already validated property for specified hvdm. The return code is ignored.

cb Count of bytes pointed to by pch. Value depends upon PropertyType:

VDMPROP_BOOL Undefined

VDMPROP_INT Undefined

VDMPROP_ENUM Length of ASCIIZ string including NULL terminator

VDMPROP_STRING Length of ASCIIZ string including NULL terminator

VDMPROP_MLSTR Length of ASCIIZ string including NULL terminator

pch Value to set/validate. The format depends on the property type:

VDMPROP_BOOL pch is interpreted as a BOOL (Boolean). Value 0 is FALSE; a nonzero value is TRUE.

VDMPROP_INT pch is interpreted as a DD, and is guaranteed to meet the registered bounds.

VDMPROP_ENUM pch points to an ASCIIZ string, and is guaranteed to be one of the registered enumeration strings.

VDMPROP_STRING pch points to an ASCIIZ string, and is guaranteed to be equal to or less than the registered maximum string length.

VDMPROP_MLSTR pch points to an ASCIIZ string. Multiple lines are separated by a line feed (0x0A). It is guaranteed to be less than or equal to the registered maximum string length.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0. VDHGetError should be called to determine the nature of the problem. A system halt occurs if:

Any of the pointers (PropertyName, HelpFile, ValidationData, or ValidationFunc) are invalid

PropertyFlag or PropertyType are invalid

A VPBOUND structure has invalid contents

The maximum string length for a VDMP_STRING is less than the length of the default string value

Purpose

Context Issues: This function can be called only in the initialization context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: VDHQueryProperty is used to obtain the value of a virtual device driver property for a particular DOS session.

VDHRegisterVDD

Format

This function registers virtual device driver entry points for use by other virtual device drivers (through VDHOpenVDD and VDHRequestVDD), and by OS/2 applications (through DosOpenVDD and DosRequestVDD).

include mvdm.inc
EXTERN VDHRegisterVDD:NEAR
VDDName DD ?	; Pointer to the name of the virtual device driver
DosReqFcn DD ?	; Function for use by DosRequestVDD
VDDReqFcn DD ?	; Function for use by VDHRequestVDD
PUSH VDDName	; Push VDDName
PUSH DosReqFcn	; Push DosReqFcn
PUSH VDDReqFcn	; Push VDDReqFcn
CALL VDHRegisterVDD	; Call the function

Parameters

VDDName (DD) Pointer to the name of the virtual device driver. Maximum length is MAXLENXDD.

DosReqFcn (DD) Function used by DosRequestVDD. NULL, if none.

The interface for the DosReqFcn is:

DosReqFcn  PROC  NEAR
; PARAMETERS
; ENTRY  [ESP + 24] - SGid    (DW) - Screen Group ID
;           [ESP + 20] - ulCmd   (DD) - Command
;           [ESP + 16] - cbIn    (DD) - Input buffer size
;           [ESP + 12] - pReqIn  (DD) - Input packet
;           [ESP +  8] - cbOut   (DD) - Output buffer size
;           [ESP +  4] - pReqOut (DD) - Output packet
; EXIT   VDDREQ_PASS  - DOS session manager calls the next routine
;                          registered under same name.
;           Non-zero     - Return failure (For APIs, 0 is success)
;           0            - Return the caller success

VDDReqFcn(DD) Function used by VDHRequestVDD. NULL, if none.

The interface for the VDDReqFcn is:

VDDReqFcn  PROC  NEAR
; PARAMETERS
; ENTRY  [ESP + 16] - hvdm (DD)    - DOS session handle
;           [ESP + 12] - ulCmd (DD)   - Command
;           [ESP +  8] - pReqIn (DD)  - Input packet
;           [ESP +  4] - pReqOut (DD) - Output packe
; EXIT   VDDREQ_PASS  - DOS session manager calls the next routine
;                          registered under same name.
;           Non-zero     - Return success (For Virtual DevHlp services, 1 is success)
;           0            - Return the caller failure

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0. If this function is called with invalid parameters or in an incorrect context, a system halt occurs.

Purpose

Context Issues: This function can be called only in the initialization context.

DOS Session Terminations: The virtual device driver must communicate with any virtual device driver or OS/2 clients, to ensure that the resources for the terminating DOS session are freed.

Notes: If a virtual device driver fails in its INIT routine after registering (through VDHRegisterVDD), the deregistration is done automatically at the time the virtual device driver is unloaded. Because two or more virtual device drivers can register the same name (VDDName), the DOS Session Manager calls each virtual device driver's routine in turn, until one of them returns a nonzero value.

Note that the order of the calling sequence is not consistent.

VDHReleaseCodePageFont

Format

This function releases a code page font loaded with VDHGetCodePageFont. If system memory was allocated to hold the specified font, this call will free that memory.

include mvdm.inc
EXTERN VDHReleaseCodePageFont:NEAR
FontPtr DD ?	; Pointer returned by VDHGetCodePageFont
PUSH FontPtr	; Push FontPtr
CALL VDHReleaseCodePageFont	; Call the function

Parameters

FontPtr (DD) Pointer returned in FontAddress by VDHGetCodePageFont.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If FontPtr is not valid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session task context.

DOS Session Terminations: The virtual device driver must call this function for any code page fonts loaded for this DOS session.

VDHReleaseMutexSem

Format

This function releases the ownership of a mutex semaphore. If the request count becomes 0 (zero), the highest priority semaphore is awakened.

include mvdm.inc
EXTERN VDHReleaseMutexSem:NEAR
MutexSemHandle DD ?	; Handle of the semaphore to be released
PUSH MutexSemHandle	; Push MutexSemHandle
CALL VDHReleaseMutexSem	; Call the function

Parameters

MutexSemHandle (DD) Handle of the semaphore to be released.

Return Codes

Success: If the function is successful, it returns nothing and the semaphore in MutexSemHandle is released.

Failure: If the virtual device driver that called VDHReleaseMutexSem is not the owner of the semaphore to be released, or if MutexSemHandle invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHRemoveFaultHook

Format

This function removes the page fault handler hook for the specified DOS session page range.

include mvdm.inc
EXTERN VDHRemoveFaultHook:NEAR
VDMHandle DD ?	; DOS session handle. 0 = current DOS session
StartingAddress DD ?	; Starting linear address
Pages DD ?	; Number of pages
PageFaultHandlerFcnPtr DD ?	; Function supplied to VDHInstallFaultHook
PUSH VDMHandle	; Push VDMHandle
PUSH StartingAddress	; Push StartingAddress
PUSH Pages	; Push Pages
PUSH PageFaultHandlerFcnPtr	; Push PageFaultHandlerFcnPtr
CALL VDHRemoveFaultHook	; Call the function

Parameters

VDMHandle (DD) DOS session handle. A value of 0 (zero) indicates the current DOS session.

StartingAddress(DD) Starting linear address.

Pages (DD) Number of pages.

PageFaultHandlerFcnPtr (DD) Function supplied to VDHInstallFaultHook. This is used to verify that the calling virtual device driver is the one that installed the fault hook.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If any of the input parameters are invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: Any fault hooks for the terminating DOS session must be released.

VDHRemoveIOHook

Format

This function must be called with StartingPort and NumPorts to remove the I/O hooks for the specified I/O ports. Port hooks cannot be removed for a subset of the range of ports hooked by VDHInstallIOHook.

include mvdm.inc
EXTERN VDHRemoveIOHook:NEAR
Reserved DD ?	; Reserved. Must be set to 0 (zero).
StartingPort DD ?	; Starting port number
NumPorts DD ?	; Number of ports in the range
IOPortHook DD ?	; Pointer to installed I/O hook entry
PUSH Reserved	; Push Reserved
PUSH StartingPort	; Push StartingPort
PUSH NumPorts	; Push NumPorts
PUSH IOPortHook	; Push IOPortHook
CALL VDHRemoveIOHook	; Call the function

Parameters

Reserved (DD) Reserved. Must be set to 0.

StartingPort (DD) Starting port number.

NumPorts (DD) Number of ports in the range.

IOPortHook (DD) Pointer to installed I/O hook entry. This parameter is used to verify that the calling virtual device driver is the one that installed the I/O hook.

Return Codes

Success: If the function was successful, it returns nothing.

Failure: If IOPortHookEntry is invalid or if StartingPort or NumPorts are out of range, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function. I/O hooks are automatically removed during DOS session termination.

Notes: If the IOPortHook is in instance data, the address passed VDHInstallIOHook must be the same address passed to VDHRemoveIOHook or VDHSetIOHookState.

VDHReportPeek

Format

This function reports DOS session polling activity. A counter of idle polling activity is incremented. If the count exceeds a threshold, the current DOS session is put to sleep for a period.

include mvdm.inc
EXTERN VDHReportPeek:NEAR
PeekWeight DD ?	; Value to add to the idle counter
PUSH PeekWeight	; Push PeekWeight
CALL VDHReportPeek	; Call the function

Parameters

PeekWeight (DD) Value to add to the idle counter.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If the current process is not a DOS session, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Any virtual device driver that can detect idle polling activity can call this service to report it. If the sum of peek weights exceeds 64KB in a single VDHGSV_MSECSBOOT clock tick (see #VDHQuerySysValue), the DOS session is considered idle. It is the responsibility of the virtual device driver to calibrate its peek weight. This depends on machine speed and the Ring 0 trap overhead time, and therefore cannot be calibrated from measuring peek rate under DOS.

Note that testing the time before the count ensures that new tests begin at the first peek in a time slice. This allows use of a very short test period .

VDHRequestMutexSem

Format

This function requests the ownership of a mutex semaphore. If the semaphore is owned and the caller is not the owner, the thread will block. If the caller is the owner, a request count is incremented. Request calls can be nested. A maximum of 65,535 (64KB) requests are allowed for each semaphore at any one time. Exceeding this limit results in a system halt.

include mvdm.inc
EXTERN VDHRequestMutexSem:NEAR
MutexSemHandle DD ?	; Mutex semaphore handle
Timeout DD ?	; Timeout (in milliseconds)
PUSH MutexSemHandle	; Push MutexSemHandle
PUSH Timeout	; Push Timeout
CALL VDHRequestMutexSem	; Call the function

Parameters

MutexSemHandle (DD) Mutex semaphore handle.

Timeout (DD) Number of milliseconds to wait before timing out the semaphore .

Return Codes

Success: If the function is successful, it returns 1.

Failure: If the function fails, it returns 0 (zero). VDHGetErrorshould be called to determine the nature of the problem. An invalid semaphore will result in a system halt. A system halt also occurs if the request count crosses the 64KB limit.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHRequestVDD

Format

This function requests an operation of a virtual device driver. This service is also used for communication between two or more virtual device drivers where dynamic linkage between them is not appropriate.

include mvdm.inc
EXTERN VDHRequestVDD:NEAR
VDDHandle DD ?	; Virtual device driver handle
VDMHandle DD ?	; DOS session handle
Command DD ?	; Command requested
InputRequestPacket DD ?	; Pointer to the input packet
OutputRequestPacket DD ?	; Pointer to the output packet
PUSH VDDHandle	; Push VDDHandle
PUSH VDMHandle	; Push VDMHandle
PUSH Command	; Push Command
PUSH InputRequestPacket	; Push InputRequestPacket
PUSH OutputRequestPacket	; Push OutputRequestPacket
CALL VDHRequestVDD	; Call the function

Parameters

VDDHandle (DD) Handle to a virtual device driver.

VDMHandle (DD) Handle to a DOS session.

Command (DD) Command requested.

InputRequestPacket (DD) Pointer to the input packet.

OutputRequestPacket (DD) Pointer to the output packet.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If VDDHandle or VDMHandle is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the task or the interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Every VDHRequestVDD procedure registered under the virtual device driver name associated with the given handle is called until one returns a nonzero value. No assumption should be made about the order of the calling sequence.

The virtual device driver worker routine sets the error with VDHSetError when it returns 0 (zero). If the calling virtual device driver is registered under the same name as the virtual device driver handle, then its entry point is also called. Furthermore, the DOS Session Manager does not prevent any of the called virtual device drivers from issuing another VDHRequestVDD.

VDHReservePages

Format

This function reserves a range of linear addresses for later use with VDHMapPages or VDHAllocPages. A reserved area cannot contain a mixture of pages set by VDHMapPages and VDHAllocPages, but it can be used successively with either one.

include mvdm.inc
EXTERN VDHReservePages:NEAR
StartingAddress DD ?	; Starting address of the linear memory to reserve
NumPages DD ?	; Number of pages to reserve
PUSH StartingAddress	; Push StartingAddress
PUSH NumPages	; Push NumPages
CALL VDHReservePages	; Call the function

Parameters

StartingAddress (DD) Starting address of the linear memory to reserve. Must be page aligned and must be less than 110000H (1MB + 64KB).

NumPages (DD) Number of pages to reserve.

Return Codes

Success: If the function is successful, it returns a nonzero value and the pages are reserved for later access.

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If StartingAddress or NumPages is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization and DOS session-task contexts. In the initialization context, the reservation affects only the global linear memory map. In the DOS session-task context, reservations affect only the local linear memory map.

DOS Session Terminations: There are no DOS session termination implications for this function. The DOS Session Manager will clean up these reservations when the DOS session terminates.

VDHResetEventSem

Format

This function resets an event semaphore.

include mvdm.inc
EXTERN VDHResetEventSem:NEAR
EventSemHandle DD ?	; Handle to the event semaphore to be reset
PUSH EventSemHandle	; Push EventSemHandle
CALL VDHResetEventSem	; Call the function

Parameters

EventSemHandle (DD) Handle to the event semaphore to be reset.

Return Codes

Success: If the function is successful, it returns nothing and the semaphore is reset.

Failure: Resetting a semaphore that is invalid or is already reset causes a system halt to occur.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHSeek

Format

This function seeks to a specified position within a file previously opened by VDHOpen.

include mvdm.inc
EXTERN VDHSeek:NEAR
FileHandle DW ?	; Handle to the file
NewOffset DD ?	; Offset of the new file-pointer position
MoveTypeFlag DD ?	; Type of move (absolute, relative )
PUSH FileHandle	; Push FileHandle
PUSH NewOffset	; Push NewOffset
PUSH MoveTypeFlag	; Push MoveTypeFlag
CALL VDHSeek	; Call the function

Parameters

FileHandle (DW) Handle to the file.

NewOffset (DD) Offset to the new file-pointer position. Depending on the value of MoveTypeFlag, this can be the offset from the beginning of the file, the ending of the file, or the current position of the file-pointer.

MoveTypeFlag (DD) Indicates what type of move is being done.

Possible values are:

VDHSK_ABSOLUTE Move file-pointer to a location relative to the beginning of the file

VDHSK_CURRENT_POSITION Move file-pointer relative to its current position

VDHSK_END_OF_FILE Move file-pointer to a location relative to the end of the file

Return Codes

Success: If the function is successful, it returns the new current absolute position of the file-pointer within the file.

Failure: If the function fails, it returns 0FFFFFFFFH. VDHGetError should be called to determine the nature of the problem. If FileHandle is invalid, or if this function is not called in the DOS session-task context, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHSendVEOI

Format

This function sends a virtual End-Of-Interrupt (EOI) signal to the Virtual Programmable Interrupt Controller (VPIC), and clears the in-service state of the IRQ for the calling device. The EOI handler for the IRQ is called, if one exists.

include mvdm.inc
EXTERN VDHSendVEOI:NEAR
IRQHandle DD ?	; IRQ handle
PUSH IRQHandle	; Push IRQHandle
CALL VDHSendVEOI	; Call the function

Parameters

IRQHandle (DD) IRQ handle.

Return Codes

Success: If the function was successful, it returns nothing.

Failure: If IRQHandle is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHSetDosDevice

Format

This function links a DOS device driver into the chain of DOS device drivers for a DOS session.

include mvdm.inc
EXTERN VDHSetDosDevice:NEAR
vpDosDD DD ?	; V86 FAR address of the DOS device driver header
PUSH vpDosDD	; Push vpDosDD
CALL VDHSetDosDevice	; Call the function

Parameters

vpDosDD (DD) V86 FAR address of the DOS device driver header. This header (and any headers chained to it) are entered into the DOS device driver list for this DOS session.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 (zero).

Purpose

Context Issues: This function can be called only in the DOS session-task context (DOS session creation only).

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHSetError

Format

This function sets the error code for return by VDHGetError.

include mvdm.inc
EXTERN VDHSetError:NEAR
ErrorCode DD ?	; Error code to set
PUSH ErrorCode	; Push ErrorCode
CALL VDHSetError	; Call the function

Parameters

ErrorCode (DD) Error code to set for VDHGetError

Return Codes

None.

Purpose

Context Issues: This function can be called in any context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This function is intended for use by any virtual device driver that offers dynamic link services to other virtual device drivers. Most of the base errors are defined in BSEERR.INC. Where possible, these definitions are used when returning errors.

VDHSetFlags

Format

This function sets the DOS session's Flags Register to specified values.

include mvdm.inc
EXTERN VDHSetFlags:NEAR
FlagValue DD ?	; DOS session flag value
PUSH FlagValue	; Push FlagValue
CALL VDHSetFlags	; Call the function

Parameters

FlagValue (DD) DOS session flag value that sets the flag register of the DOS session.

Return Codes

None.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Virtual device drivers must use this interface instead of the client register frame pointer to change the DOS session's flags. Changes to the interrupt flag and the I/O Privilege Level (IOPL) field must be under the control of 8086 emulation so that VDHArmSTIHook works correctly.

Nested Task (NT) and Resume Flag (RF) flags are cleared, the virtual 8086 Mode (VM) flag is set, and the IOPL field is left unchanged. This function does not take effect until the operating system returns to V86 mode.

VDHSetIOHookState

Format

This function is used to enable and disable I/O port trapping for a range of ports.

include mvdm.inc
EXTERN VDHSetIOHookState:NEAR
Reserved DD ?	; Reserved. Must be set to 0
StartingPort DD ?	; Starting port number
NumPorts DD ?	; Number of ports in the range
IOPortHook DD ?	; Pointer used to install I/O hooks
EnableFlag DD ?	; FLag for setting I/O hooks
PUSH Reserved	; Push Reserved
PUSH StartingPort	; Push StartingPort
PUSH NumPorts	; Push NumPorts
PUSH IOPortHook	; Push IOPortHook
PUSH EnableFlag	; Push EnableFlag
CALL VDHSetIOHookState	; Call the function

Parameters

Reserved (DD) Reserved. Must be set to 0 (zero).

StartingPort (DD) Starting port number.

NumPorts (DD) Number of ports in the range.

IOPortHook (DD) Pointer used to install I/O hooks. This is used to verify that the calling virtual device driver is the one that installed the I/O hooks.

EnableFlag (DD) Flag for setting I/O hooks.

TRUE (Non-zero). Enable I/O hooks.

FALSE (0). Disable I/O hooks.

Return Codes

Success: If the function was successful, it returns nothing.

Failure: If IOPortHook is invalid, or if StartingPort or NumPorts are out of range, or if StartingPort and NumPorts overlap a range of ports previously marked as VDHIIH_ALWAYS_TRAP by VDHInstallIOHook, a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: If the IOPortHook is in instance data, the address passed to VDHInstallIOHook must be the same address passed to VDHRemoveIOHook or VDHSetIOHookState. When trapping is enabled, the I/O port hooks for the specified range get control when a DOS session does I/O to that range. When trapping is disabled, DOS session I/O goes directly to the physical hardware ports. None of the ports in the range can be marked as VDHIIH_ ALWAYS_TRAP by VDHInstallIOHook.

VDHSetPriority

Format

This function adjusts a DOS session's scheduler priority class and level. Priority levels within each priority class range from 0 - 31.

include mvdm.inc
EXTERN VDHSetPriority:NEAR
VDMHandle DD ?	; Handle to the DOS session with the priority to change
ActionClassFlag DD ?	; Dual purpose flag, Action and Class
NewPriority DD ?
PUSH VDMHandle	; Push VDMHandle
PUSH ActionClassFlag	; Push ActionClassFlag
PUSH NewPriority	; Push NewPriority
CALL VDHSetPriority	; Call the function

Parameters

VDMHandle (DD) Handle to the DOS session with the priority to change.

ActionClassFlag (DD) A dual-purpose flag.

The Class component of ActionClassFlag indicates the class to which the DOS session should be changed. The Action component of the ActionClassFlag allows the virtual device driver to manage when the priority is changed, and when to start, end, or continue use of the class. See "Notes" under Purpose.

The value of the Class component can be one of the following:

VDHSP_TIME_CRITICAL Highest priority

VDHSP_SERVER Highest priority

VDHSP_REGULAR Highest priority

VDHSP_IDLE Lowest priority

VDHSP_NO_CHANGE Do not change the DOS session's class

The value of the Action component can be one of the following:

VDHSP_START_USE Start use of a class

VDHSP_CONTINUE_USE Continue use of a class

VDHSP_END_USE End use of a class

VDHSP_DEFAULT_ACTION If no action is specified, the default class is changed

NewPriority(DD) Change from the DOS session's previous priority level.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If VDMHandle or ActionClassFlag are invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the task or interrupt contexts.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: A count of the current users is maintained at each class. The actual priority class in effect at any time is always the highest priority class with current declared users. When there are no declared users, the default class is used. Changes to a class other than the effective class are made to saved values. These changes take effect when the class becomes the effective class.

The caller must signal when it begins use of the class, when it makes changes within the class, and when it finishes with the class. The typical user would make one or more changes to priority at a particular class, and finish the series of changes at the class. The virtual device driver uses the VDHSP_START_USE and VDHSP_END_USE flags at the first and last calls within the class, and the VDHSP_CONTINUE_USE flag for changes in between.

The default class is normally VDHSP_REGULAR unless the class or NewPriority is changed without declaring a user (that is, without specifying a start, continue, or end action flag). This allows a user interface to adjust the default priority of a DOS session.

VDHSetVIRR

Format

This function sets the Virtual Interrupt Request Register (VIRR) in the Virtual Programmable Interrupt controller (VPIC) of the specified DOS session for the IRQ specified. This causes an interrupt to be simulated to the DOS session.

include mvdm.inc
EXTERN VDHSetVIRR:NEAR
VDMHandle DD ?	; DOS session handle
IRQHandle DD ?	; Handle from VDHOpenVIRQ
PUSH VDMHandle	; Push VDMHandle
PUSH IRQHandle	; Push IRQHandle
CALL VDHSetVIRR	; Call the function

Parameters

VDMHandle (DD) DOS session handle. A value of 0 (zero) indicates the current DOS session.

IRQHandle(DD) IRQ handle from VDHOpenVIRQ.

Return Codes

Success: If the function was successful, it returns nothing.

Failure: If either of the parameters is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: If the interrupt request has not been cleared when the DOS session issues an End-Of-Interrupt (EOI), another interrupt will be simulated to the DOS session.

VDHSetVPMExcept

Format

This function sets the current value in the protected-mode exception table.

include mvdm.inc
EXTERN VDHSetVPMExcept:NEAR
Vector DD ?	; Interrupt vector number
HandlerAddress DQ ?; Far32 handler address
Flag DB ?; Flag indicating exception handler
PUSH Vector	; Push Vector
PUSH HandlerAddress	; Push HandlerAddress
PUSH Flag	; Push Flag
CALL VDHSetVPMExcept	; Call the function

Parameters

Vector (DD) Interrupt vector number.

HandlerAddress (DQ) Far32 handler address.

Flag (DB) Flag indicating the kind of exception handler being registered.

Possible value:

VPMXCPT32 A 32-bit handler is being registered.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure: If the function fails, it returns 0 (zero).

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: There must be a DPMI client running in the DOS session before calling this function.

VDHSetVPMIntVector

Format

This function sets the application Ring 3 handler in the protected-mode interrupt chain. This is used only for DOS Protect Mode Interface (DPMI) support.

include mvdm.inc
EXTERN VDHSetVPMIntVector:NEAR	Vector DD ?	; Interrupt vector number
HandlerAddress DQ ?; Far32 handler address
Flag DB ?; Flag.
PUSH Vector	; Push Vector
PUSH HandlerAddress	; Push HandlerAddress
PUSH Flag	; Push Flag
CALL VDHSetVPMIntVector	; Call the function

Parameters

Vector (DD) Interrupt vector number.

HandlerAddress (DQ) Far32 handler address.

Flag (DB) Flag.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure If the function fails, it returns 0 (zero).

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: There must be a DPMI client running in the DOS session before calling this function.

VDHSwitchToVPM

Format

This function switches the current DOS session into protected mode. This assumes that the appropriate initializations have already been performed.

include mvdm.inc
EXTERN VDHSwitchToVPM:NEAR
DD ?
PUSH	; Push
CALL VDHSwitchToVPM	; Call the function

Parameters

(DD) None.

Return Codes

None.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHSwitchToV86

Format

This function switches the current DOS session to V86 mode.

include mvdm.inc
EXTERN VDHSwitchToV86:NEAR
DD ?
PUSH ; Push
CALL VDHSwitchToV86 ; Call the function

Parameters

(DD) None.

Return Codes

None.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHThawVDM

Format

This function reverses the effect of VDHFreezeVDM. The specified DOS session is allowed to run when the freeze count becomes 0 (zero).

include mvdm.inc
EXTERN VDHThawVDM:NEAR
VDMHandle DD ?  ; Handle to the DOS session to thaw
PUSH VDMHandle  ; Push VDMHandle
CALL VDHThawVDM ; Call the function

Parameters

VDMHandle (DD) Handle to the DOS session to allow to execute (thaw).

Return Codes

Success: If the function is successful, it returns nothing. The freeze count for the DOS session is decremented.

Failure: If VDMHandle is an invalid handle, a system halt occurs.

Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This function does nothing if called on behalf of a DOS session that is not frozen. See #VDHFreezeVDM for a full discussion of freeze counting.

VDHUnlockMem

Format

This function reverses the effect of VDHLockMem, unlocking a previously locked area of memory.

include mvdm.inc
EXTERN VDHUnlockMem:NEAR
LockHandle DD ?   ; Lock handle from VDHLockMem
PUSH LockHandle   ; Push LockHandle
CALL VDHUnlockMem ; Call the function

Parameters

LockHandle (DD) Lock handle of a locked memory area. Originally obtained from VDHLockMem.

Return Codes

Success If the function is successful, it returns nothing.

Failure An invalid lock handle causes a system halt to occur.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Because lock handles are global, this function can be made in any task context.

VDHUnreservePages

Format

This function unreserves pages that were previously reserved with VDHReservePages. The starting address and size must be identical to the previous corresponding call to VDHReservePages. Note that any mapping made earlier on this region is unmapped before calling this function.

include mvdm.inc
EXTERN VDHUnreservePages:NEAR
StartingAddress DD ?   ; Starting address of the region to unreserve
NumPages DD ?          ; Size of the region to unreserve, in pages
PUSH StartingAddress   ; Push StartingAddress
PUSH NumPages          ; Push NumPages
CALL VDHUnreservePages ; Call the function

Parameters

StartingAddress (DD) Starting address of the region to unreserve. Must be less than 110000H (1MB+64KB) and must be page-aligned. In addition, StartingAddress must match a previous VDHReservePages call.

NumPages (DD) Size, in pages, of the region to unreserve. Must match the corresponding parameter to a previous call to VDHReservePages.

Return Codes

Success: If the function is successful, it returns nothing.

Failure: If StartingAddress or NumPages is invalid, or if they were not used together in an earlier call to VDHReservePages, a system halt occurs.

Purpose

Context Issues: This function can be called in the initialization or DOS session-task context (DOS session creation). In the initialization context, memory can be unreserved only from the global linear memory map. In the DOS session-task context, memory can be unreserved only from the local linear memory map.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: StartingAddress must be less than 110000H(1MB+64KB) and must be page -aligned. Additionally, StartingAddress must match a previous call to VDHReservePages. NumPages must match the corresponding parameter to a previous call to VDHReservePages.

VDHWaitEventSem

Format

This function is used to wait on an event semaphore. If the semaphore is posted, it will return immediately.

include mvdm.inc
EXTERN VDHWaitEventSem:NEAR
EventSemHandle DD ? ; Event semaphore handle
Timeout        DD ? ; Timeout (in milliseconds)
PUSH EventSemHandle ; Push EventSemHandle
PUSH Timeout        ; Push Timeout
CALL VDHWaitEventSem; Call the function

Parameters

EventSemHandle (DD) Event semaphore handle.

Timeout (DD) Number of milliseconds to wait before timing out.

Return Codes

Success: If the function is successful, it returns 1 (one).

Failure: If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If EventSemHandle is invalid , a system halt occurs.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function. If Timeoutis 0 (zero), the caller will not block; however, ERROR_TIMEOUT is returned. If Timeoutis -1, the caller is blocked until the semaphore is posted. Otherwise, the caller blocks for the time specified (in milliseconds) in Timeout.

VDHWaitVIRRs

Format

This function waits until any virtual interrupt is simulated to the current DOS session.

include mvdm.inc
EXTERN VDHWaitVIRRs:NEAR
PostInFcnHook DD ? ; Hook handle
PUSH PostInFcnHook ; Push PostInFcnHook
CALL VDHWaitVIRRs  ; Call the function

Parameters

PostInFcnHook (DD) Hook handle of a routine that is to be called after interrupts are simulated.

Return Codes

Success: The function returns a nonzero value, if it woke up because of a simulated interrupt. If it woke up because of a VDHWakeVIRRs call, the function returns 0 (zero).

Failure: If the function fails, it returns nothing.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: The hook handle must be allocated as a VDH_WAITVIRRS_HOOK type. This function is intended for virtual device drivers that need to simulate a spin loop without stopping virtual interrupt simulation. This allows the virtual device driver to be compatible with DOS but avoid wasting CPU time in a spin loop.

The DOS session's interrupts must be enabled, using VDHSetFlags, before this service is used.

Generally, the virtual device driver will be in a loop when calling this function. When it returns a nonzero value, the virtual device driver returns to V86 mode so that the interrupt can be simulated. The hook function passed to this service is executed after all interrupts are simulated. When this function returns 0 (zero), it is because some other portion of the virtual device driver (likely in response to a physical hardware interrupt) has determined that the DOS session no longer needs to spin. The virtual device driver exits the loop at this point.

The virtual keyboard device driver behaves in this manner in order to emulate the ROM BIOS Read Keyboard function (INT 16H, AH=00) without using excessive CPU time, by allowing the ROM BIOS to spin out in V86 mode, or stopping simulated interrupts by performing a VDHWaitEventSem.

VDHWakeIdle

Format

This function notes that the DOS session is busy (doing useful work). If the DOS session is currently sleeping or running at a lower priority because of the polling activities, the DOS session is awakened, its priority is restored, and it is no longer considered idle.

include mvdm.inc
EXTERN VDHWakeIdle:NEAR
VDMHandle DD ?   ; Handle to the DOS session to wake up
PUSH VDMHandle   ; Push VDMHandle
CALL VDHWakeIdle ; Call the function

Parameters

VDMHandle (DD) Handle to the DOS session to be awakened.

Return Codes

None.

Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHWakeVIRRs

Format

This function wakes up a DOS session that is waiting with the VDHWaitVIRRs service. See VDHWaitVIRRs for a full description of the use of this function.

include mvdm.inc
EXTERN VDHWakeVIRRs:NEAR
VDMHandle DD ?    ; Handle of the DOS session to wake up
PUSH VDMHandle    ; Push VDMHandle
CALL VDHWakeVIRRs ; Call the function

Parameters

VDMHandle (DD) Handle of the DOS session to be awakened.

Return Codes

Success: If the function was successful, it returns nothing.

Failure: If VDMHandle is invalid, a system halt occurs.

Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Use with caution because it wakes up every virtual device driver that is waiting on a VDHWaitVIRRs.

VDHWrite

Format

This function writes bytes to a file or device previously opened by VDHOpen.

include mvdm.inc
EXTERN VDHWrite:NEAR
FileHandle DW ?     ; Handle to the file or device to write to
WriteBufferPtr DD ? ; Pointer to the buffer to write
NumBytes DD ?       ; Number of bytes to write
PUSH FileHandle     ; Push FileHandle
PUSH WriteBufferPtr ; Push WriteBufferPtr
PUSH NumBytes       ; Push NumBytes
CALL VDHWrite       ; Call the function

Parameters

FileHandle (DW) Handle to the file or device to write to.

WriteBufferPtr (DD) Pointer to the buffer to write.

NumBytes (DD) Number of bytes to write.

Return Codes

Success: If the function is successful, it returns a count of the bytes written. This can be equal to 0 (zero).

Failure If the function fails, it returns 0FFFFFFFFH. VDHGetError should be called to determine the nature of the problem. If FileHandle is invalid, or this function is called in any context except DOS session-task, a system halt occurs.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHWriteUBuf

Format

This function writes to protected-mode address space as if access were done at Ring 3. This means checking for supervisor and read-only faults, and trapping any other faults. All faults are passed on to the DOS session application handler through VDHRaiseException.

include mvdm.inc
EXTERN VDHWriteUBuf:NEAR
SourceBuffer DD ?  ; Source buffer from which to copy
ByteCount DD ?     ; Count of bytes
Selector DW ?      ; Application selector
OffsetPointer DD ? ; Address of the variable containing the offset
Flag DD ?          ; Flag for checking controls
PUSH SourceBuffer  ; Push SourceBuffer
PUSH ByteCount     ; Push ByteCount
PUSH Selector      ; Push Selector
PUSH OffsetPointer ; Push OffsetPointer
PUSH Flag          ; Push Flag
CALL VDHWriteUBuf  ; Call the function

Parameters

SourceBuffer (DD) Source buffer from which to copy.

ByteCount (DD) Count of bytes.

Selector (DW) Application selector.

OffsetPointer (DD) Address of the variable containing the offset for the start of the write.

Flag (DD) Checking control.

Possible values are:

VPM_PROT_READ Check for read.

VPM_PROT_WRITE Check for write.

VPM_FAULT_IF_SU_SET Fault, if supervisor pages.

VPM_FAULT_IF_RO Fault, if writing to read-only descriptor.

VPM_SEL_PRESENT Caller knows descriptor is present.

VPM_SEL_WRITEABLE Caller knows descriptor is writable.

VPM_SEL_IS_SS Selector is client's stack.

VPM_XCPTRET_ALT After exception, return to alternate mode. For example, if the client was in protected mode when the service was called, return in V86 mode after the exception is handled.

Return Codes

Success: If the function is successful, it returns a nonzero value.

Failure If the function fails, it returns 0 (zero) if there is a bad address reference, which causes a fault. In such a case, OffsetPointer is updated with the address of the fault. For Selector Faults, OffsetPointer remains unchanged.

Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: When the routine fails, the caller must clean up and exit so that the exception can be simulated to the user.

VDHYield

Format

This function yields the processor to any other thread of equal or higher priority.

include mvdm.inc
EXTERN VDHYield:NEAR
OptionFlag DD ? ; Yield options
PUSH OptionFlag ; Push OptionFlag
CALL VDHYield   ; Call the function

Parameters

OptionFlag (DD) Yield options.

Possible value:

VDH_YIELD_TIME_CRITICAL Yield only to time-critical threads.

Return Codes

None.

Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: If OptionFlag is VDH_YIELD_TIME_CRITICAL, and no time-critical thread is able to run, the caller keeps the CPU.