Windows 3.1 Virtual Device Adaptation Guide

References

FastDisk Device

Copyright

Database Version


Virtual Device References

Virtual Block Device

Virtual Communications Device

Virtual Display Device

Virtual DMA Device

Virtual EBIOS Device

Virtual Hard Disk Device

Virtual Interrupt 13 Device

Virtual Keyboard Device

Virtual Math Coprocessor Device

Virtual Mouse Device

Virtual MS-DOS Manager

Virtual MS-DOS Network Device

Virtual PageSwap Device

Virtual PIC Device

Virtual Polling Device

Virtual Shell Device

Virtual Sound Device

Virtual Timer Device

Virtual V86 Mode Memory Manager

VMM Control Messages

VMM Macros

VMM Services

VMM Structures


Virtual Machine Manager Services

Break Point and Callback Services

Debugging Services

Error Handling Services

Event Services

I/O Trapping Services

Information Services

Initialization Information Services

Interrupts and Callback Services

Linked List Services

Miscellaneous Services

Nested Execution Services

Primary Scheduler Services

Processor Fault and Interrupt Services

Protected-Mode Execution Services

Time-Slice Scheduler Services

Timing Services

VMM Memory Management Services


Copyright

Information in this on-line help system is subject to change without

notice and does not represent a commitment on the part of Microsoft

Corporation. The software and/or files described in this on-line help

system are furnished under a license agreement or nondisclosure

agreement. The software and/or files may be used or copied only in

accordance with the terms of the agreement. The purchaser may make one

copy of the software for backup purposes. No part of this on-line help

system may be reproduced or transmitted in any form or by any means,

electronic or mechanical, including photocopying, recording, or

information and retrieval systems, for any purpose other than the

purchaser's personal use, without the written permission of Microsoft

Corporation.


Version

Microsoft Windows

Virtual Device Adaptation Guide

Version 3.1


FastDisk Device

Introduction

FastDisk is the name for a group of Windows Virtual Devices (VxDs) that allow for direct, asynchronous I/O to hard disks or other block devices such as optical disks or tape backup devices. This technology improves performance by supporting such features as true read-ahead and write-behind paging and file caching. Also, since FastDisk can be called at ring 0, MS-DOS programs running in virtual machines can be paged while they run.

At the heart of FastDisk is a virtual device named BLOCKDEV. This virtual device replaces the Windows 3.0 VHD (Virtual Hard Disk Device) and provides a new set of services to support multiple block device drivers. BlockDev performs all of the functions that VHD supported in Windows 3.0. This includes entering critical sections during Int 13h calls to the BIOS disk interface, allocating DMA buffers when DMA hard disks are detected, and improving the performance of hard disks that do not have FastDisk device drivers.

BlockDev is also responsible for providing a common interface between the FastDisk block devices and their clients. Under a default Windows 3.1 configuration there will be at most two users of a FastDisk device: the BIOS Int 13h translation virtual device, and PageFile, the device that is responsible for performing demand paging I/O.

The Int 13h BIOS API translation virtual device is responsible for translating disk I/O requests for drives that have a FastDisk device driver into commands that the FastDisk device driver can understand.

For the sake of this discussion, we will call block device drivers FastDisks, the BlockDev virtual device is BlockDev, and device drivers that send commands to FastDisks are clients.

The FastDisk device drivers themselves can be very simple. They are only required to support multiple sector read and write commands. Commands are always submitted in arbitrarily long chains of command blocks, but FastDisk device drivers can choose to have BlockDev queue the commands and send them the FastDisk virtual device one command at a time. This greatly reduces the amount of work needed to support a new hardware controller.

Initialization Sequence

During the Sys_Critical_Init phase of Win386 initialization, BlockDev initializes and prepares for FastDisk device drivers to register themselves. Each FastDisk then identifies itself by calling the BlockDev_Register_Device service during initialization. This is usually done during the Sys_Critical_Init phase of initialization, but can be done during the Device_Init phase if necessary. However, FastDisks must be careful to initialize before any client attempts to locate them. For example, any FastDisk that will be used by the standard PageFile virtual device must either initialize during Sys_Critical_Init or must initialize during Device_Init and have an initialization order that is less than PageFile's. Note that the Int 13h translation virtual device is an exception to this rule since BlockDev notifies Int13.386 every time an Int 13h FastDisk initializes.

Clients usually will attempt to locate a FastDisk's BDD during either the Device_Init or Init_Complete phase of device initialization. However, it is possible for a client to search the BDD chain at any point in time. Client's may attempt to locate a FastDisk either by examining the Int 13h drive number in the BDD or by searching for a particular device name.

Establishing Communication With a FastDisk Device Driver

Every FastDisk is identified by a unique Block Device Descriptor. This data structure contains fields used to identify the type of device, it's name, it's physical characteristics such as number of heads, cylinders, and sectors per track, and various code entry points. Most of the information in the BDD is reserved for use by BlockDev, however, clients are allowed to scan a list of BDDs for all installed FastDisks and examine the name, flags, and Int 13h drive number fields.

The BDD_Major_Ver and BDD_Minor_Ver fields define the version of BlockDev support that is required by this FastDisk, not the FastDisk's version number.

BDD_Device_Type identifies the FastDisk as a fixed disk, floppy, tape, and so on.

BDD_Int_13h_Number identifies the FastDisk's Int 13h drive number if it has one. Note that this field is ignored unless the BDF_Int13_Drive flag is set in the BDD_Flags field.

BDD_Flags is a bit field that defines various properties about the FastDisk's capabilities.

BDD_Name_Ptr points to a null terminated string that is used to uniquely identify the FastDisk.

BDD_Max_Sector defines the highest valid sector number for this FastDisk. Sector numbers start at 0 and the max sector value is inclusive. Therefore, a max sector number of 1000h would mean that the drive has 1001h sectors, numbered 0 through 1000h.

BDD_Sector_Size specifies the size of a single sector in bytes. Note that for Int 13h drives this value must by 200h (512 decimal).

The BDD_Num_Heads, BDD_Num_Cylinders, and BDD_Num_Sectors_Per_Track specify the physical characteristics of the drive. The Int 13h translation virtual device will use these values to convert Int 13h calls from virtual mode into FastDisk commands. Other virtual devices, such as disk caches, may also use this information to optimize I/O. Block devices that are not disk drives do not need to fill in these fields.

BDD_Sync_Command_Proc specifies the address for synchronous commands to be sent to a FastDisk. Note that clients should never call this address directly. Clients must always call BlockDev_Synchronous_Command to communicate with a FastDisk.

BDD_Command specifies the address for asynchronous commands to be sent to a FastDisk. Note that clients should never call this address directly. Clients must always call BlockDev_Send_Command to communicate with a FastDisk.

The BDD_Hw_Int_Proc is called whenever a hardware interrupt occurs on IRQ 14. If this field is 0 then BlockDev will not call the FastDisk when interrupts occur. This allows devices to be written that use an interrupt other than IRQ 14.

The procedure must return with the carry flag clear if the fastdisk has serviced the hardware interrpt, carry set if it has not seviced the interrupt. FastDisk device drivers must call VPICD_Phys_EOI to end the physical interrupt before returning with carry clear. FastDisks may not use any of the VPICD services related to virtual interrupts. They may only call the following VPICD services:

VPICD_Get_Version

VPICD_Phys_EOI

VPICD_Get_Complete_Status

VPICD_Get_Status

VPICD_Test_Phys_Request

VPICD_Physically_Mask

VPICD_Physically_Unmask

VPICD_Get_IRQ_Complete_Status

It is important to only rely on the state of the actual physical interrupt controller so that these virtual devices can be used in future environments that do not have virtual interrupt support.

FastDisk Commands

A pointer to a BDD is used to identify which FastDisk the command is to be sent to. A second pointer points to the head of a linked list of command blocks to be sent to the device. The  client  then  calls  the  service BlockDev_Send_Command to send the command to the FastDisk.

Because all commands are asynchronous, the send command service will not return any status information about the command(s) sent. When a command completes, the caller will be called back at an address specified in the command block.

The basic commands are read, write, and cancel. Any command that has been sent to a FastDisk but has not yet completed can be canceled (although commands that are in progress usually can not be canceled).

Client Interfaces to FastDisks

Locating a FastDisk

During initialization, clients must identify the FastDisk(s) with which they will need to communicate. The Int 13h virtual device is notified by BlockDev whenever an Int 13h FastDisk is installed, but other clients, such as PageFile, will need to request information from BlockDev to locate their block devices. BlockDev supports this through two services:

BlockDev_Find_Int13_Drive (can only be called during initialization)

BlockDev_Get_Device_List

The BlockDev_Find_Int13_Drive service is provided as a convenience for clients that  only understand how to communicate with FastDisks that are standard Int 13h drives. The default PageFile's swap partition is created only on Int 13h drives by the SwapFile utility. Therefore, PageFile knows that it will always be communicating with a FastDisk that is also an Int 13h drive.

However, this is just a restriction of the default Windows 3.1 PageFile virtual device. PageFile could easily be extended to use other block device drivers such as dedicated hard disks that are used only for paging and can not be accessed through the standard Int 13h BIOS interface. Also, other virtual devices may need to communicate with block device drivers, such as tape drives, which do not use the Int 13h BIOS disk interface. To locate these device drivers, the client must call BlockDev_Get_Device_List to obtain a pointer to the head of a list of all currently installed block device drivers. The client can then scan this list, checking the name field of each BDD, until the appropriate device driver is located.

Once the address of a BDD of a FastDisk is located, that address is used to indicate the destination for commands when calling BlockDev_Send_Command.

Sending Asynchronous Commands to a FastDisk virtual device

BlockDev_Send_Command Service Interface

All commands are sent to FastDisk virtual devices by calling the service BlockDev_Send_Command with the following parameters:

EDI -> Block Device Descriptor

ESI -> First command block in list of commands to send

This service has no return values. Each command in a command chain  will call a command complete callback procedure when the command has been completed or if an error is detected.

Command blocks contain a field CB_Reserved_Client that can be used by the client to uniquely identify the command block when it completes. BlockDev will not use or modify any data in the portion of the command block.

This service can be called from an interrupt handler. This allows clients to submit a new command to a FastDisk from a command complete callback procedure.

Command Block Structure

   BlockDev_Command_Block STRUC

   BD_CB_Next       dd   ?

   BD_CB_Command      dw   ?

   BD_CB_Cmd_Status    dw   ?

   BD_CB_Flags       dd   ?

   BD_CB_Cmd_Cplt_Proc   dd   ?

   BD_CB_Sector      dq   ?

   BD_CB_Count       dd   ?

   BD_CB_Buffer_Ptr    dd   ?

   BD_CB_Reserved_Client  dd   ?

   BD_CB_Reserved_BlockDev dd   ?

   BD_CB_Reserved_FastDisk dd   ?

   BlockDev_Command_Block ENDS

Priorities

Commands have one of two priorities: High priority, or not high priority. A high priority command is indicated by setting the appropriate flag in the command block. All high priority commands will be processed before non-high priority commands. However, if a low priority command is in progress when a high priority command is submitted, the command that is in progress will usually be completed before the high priority command begins. Any queued low priority commands will not be processed until all high priority commands have completed.

Command Complete CallBack

When a command execution completes, the command complete callback procedure will be called to notify the caller of the status of the operation. The callback procedure will be called with the following parameters:

   EDI -> Block Device Descriptor

   ESI -> Command Block

Interrupts will be disabled; client is allowed to enable interrupts.

The client  must examine the command status field to determine wether or not the command has succeeded. Once the command complete callback has been called, the command block is no longer busy, and may be used again immediately. It is valid to call BlockDev_Send_Command from a command complete callback procedure. Note, however, that the callback will be called at interrupt time and so only Async services may be called. If the virtual device needs to call any other services then it should schedule an event and complete the processing of  the command  completion when the event procedure is called.

Upon command completion the following fields may have been modified in the command block:

BD_CB_Next

BD_CB_Cmd_Status

BD_CB_Reserved_BlockDev

BD_CB_Reserved_FastDisk

All other fields will remain unmodified. This allows clients to easily re-submit the same command block without having to completely reinitialize it each time.

Standard Commands

Read/Write Sectors

The read and write commands take identical parameters except for the command word. These commands use every parameter in the BlockDev_Command_Block structure. The caller specifies the address of a buffer and the starting sector at which the I/O should begin. If the scatter/gather option is not selected then the buffer pointer points to a buffer large enough to accept the entire transfer, and the count field contains the number of sectors to transfer. If the scatter/gather option flag is set then the count field is ignored and the buffer pointer points to an array of transfer addresses and counts. The scatter/gather table has the following format:

Dword count of sectors for memory region 1

Dword linear address for transfer of region 1 sectors

Dword count of sectors for memory region 2

Dword linear address for transfer of region 2 sectors

  .

  .

  .

Dword count of sectors for memory region x

Dword linear address for transfer of region x sectors

Dword 0 to terminate list

It is the client's responsibility to ensure that all memory that is passed to this service is page locked.

The priority of the command is indicated in the flag word as either high priority or not high priority. High priority commands will be serviced before all other commands.

When  the  command  completes, the address in BD_CB_Cmd_Cplt_Proc will be called with the following parameters:

EDI -> Block Device Descriptor

ESI -> Command block for command that has completed

Interrupts are disabled. The client may enable interrupts and may return with interrupts enabled if desired.

The caller is allowed to modify EAX, EBX, ECX, EDX, ESI, EDI, and flags.

Verify Sectors

The verify command is similar to a read command except that no data is transferred. The caller must fill in the command, flags, starting sector, and sector count fields. There is no need to fill in the buffer pointer field since no data will be transferred. Obviously, scatter/gather is not supported for verify commands. Some FastDisk device drivers may not support this command and will complete the command with a status of BDS_Invalid_Command.

Cancel

Commands that have been sent to a FastDisk, but have not yet completed, can be canceled by sending a cancel command. The client specifies the command to cancel by placing a pointer to the command in the BC_CB_Buffer_Ptr field of the cancel command block.

If it is possible to cancel the command, the canceled command's command complete callback will be executed and the command will complete with a status of BDS_Canceled. After the canceled command has been canceled, then the cancel command will be completed, and it's callback will be executed with a status of BDS_Success. In all cases, if a command is canceled, the canceled command's command complete callback will be called before the cancel command's callback is called.

If the command that was to be canceled is already in progress or is not in the current command queue for the FastDisk, the cancel command will fail with a status of either BDS_Cmd_In_Progress, or BDS_Invalid_Cmd_Ptr.

Invalid and Unsupported Commands

Any command that is not supported by a FastDisk will complete with a status of BDS_Invalid_Command.

FastDisk Interfaces With BlockDev

Block Device Descriptor

Every FastDisk is identified by a unique Block Device Descriptor (BDD). The BDD identifies the device's name, physical characteristics, several entry points, and other information. FastDisks register their presence by calling BlockDev_Register_Device  during  system  initialization (usually during the Sys_Critical_Init control call). Note that a single virtual device may register more than one BDD. This may be the case, for example, with a controller that supports multiple hard disk drives. A single virtual device would support more than one FastDisk.

One important consideration when writing a FastDisk is wether or not the device will support chained commands. All clients may submit multiple commands, however a FastDisk has the option  of requesting that BlockDev serialize all commands so that the FastDisk is only required to execute one command at a time. This is accomplished by setting the BDF_Serial_Cmd flag in the BDD flag dword. If this option is selected then BlockDev will queue all commands and only present the FastDisk with a single command at a time. BlockDev will also validate sector ranges for read and write commands. FastDisks will never need to test for invalid sectors on these commands if BDF_Serial_Cmd is selected. Also, BlockDev will handle all cancel commands. The FastDisk will never see either the command that was canceled or the cancel command itself.

FastDisk device drivers for controllers that can handle multiple commands may not want commands serialized by BlockDev. In this case, the FastDisk is responsible for queueing commands and performing all error checking for every command. BlockDev will simply pass all command chains through to the FastDisk block device driver.

Command Procedures

Two fields that are required to be supplied in every BDD are the BDD_Sync_Cmd_Proc and BDD_Command_Proc callback entry points. These fields specify a procedures to be called whenever a client sends commands to the FastDisk. Clients never call the entry points directly. Instead, clients send command chains to a FastDisk by calling the BlockDev_Synchronous_Command and BlockDev_Send_Command services.

Synchronous Commands

Synchronous commands are passed directly to the FastDisk. These commands behave like normal procedure calls in that the result of the command is returned to the caller when the procedure call returns (BlockDev_Send_Command has no return results). Currently, the  only defined command is BD_SC_Get_Version. This command has the following entry and exit parameters:

ENTRY:

AX = BD_SC_Get_Version

EDI -> Block Device Descriptor (required for all commands)

EXIT:

Carry flag is clear (this call always succeeds)

AH = FastDisk major version number

AL = FastDisk minor version number

All fastdisks must support this command. The synchronous command ID is always placed in the AX register. ISVs may support device-dependent APIs using commands 8000h-FFFFh. Microsoft reserves commands 0000h-7FFFh for future expansion of the standard FastDisk API.

On return, the carry flag is always used to indicate an error. In case of an error, the error number will be returned in AX. All synchronous commands that are not recognized by a FastDisk should return with carry set and AX=BD_SC_Err_Invalid_Cmd.

Asynchronous Commands

BlockDev then does one of two things depending upon the BDF_Serial_Cmd flag in the fastdisk's BDD. If the flag is clear (the FastDisk can handle multiple, chained commands), the fastdisk's command procedure is called with the original client command chain. In this case, BlockDev will do no error checking or processing of the command list in any way.

If the serial command option is set in the fastdisk's BDD then BlockDev will process the entire command chain before sending the commands to the FastDisk. In this case, BlockDev will queue commands so that high priority commands will be processed ahead of all non-high priority commands regardless of the client that submitted them. It will also check for invalid sector ranges and any invalid command blocks will be completed without the FastDisk ever seeing them. If a command is canceled that is in the command queue, BlockDev will handle the cancel without the FastDisk ever seeing the command. Commands will be sent to the FastDisk one  at a  time. When the FastDisk calls BlockDev_Command_Complete for the current command, BlockDev will immediately submit the next command in the queue if any are pending.

Command Completion

When a command completes, the FastDisk must call the BlockDev_Command_Complete service with the following parameters:

EDI -> Fastdisk's BDD

ESI -> Command block for command that completed

The FastDisk is responsible for updating the BD_CB_Cmd_Status field as well as changing any other fields that should be modified for the command. BlockDev will then call the command complete callback address specified in the command. FastDisk virtual device should never call the command complete address directly. They should always call BlockDev_Command_Complete. If BlockDev is serializing commands for the FastDisk then a new command may be send to the fastdisk's command procedure before this service returns.


Break Point and Callback Services

Allocate_V86_Call_Back	Allocates a V86 mode callback

Allocate_PM_Call_Back	Allocates a protected-mode callback

Call_When_VM_Returns	Installs a return-from-interrupt callback

Install_V86_Break_Point	Installs a break-point callback

Remove_V86_Break_Point	Removes a V86 break point


Allocate_V86_Call_Back
include vmm.inc

mov     edx, OFFSET32 RefData   ; reference data (any doubleword)

mov     esi, OFFSET32 Callback  ; callback procedure to call

VMMcall Allocate_V86_Call_Back

jc      error

mov     [CallbackAddr], eax     ; segment:offset for callback

The Allocate_V86_Call_Back service installs a callback procedure that V86 mode applications can call to execute code in a virtual device. The service returns a callback address, specified as segment:offset pair. When V86 mode applications call this address, the system passes control to the callback procedure specified by the Callback parameter.

Virtual devices typically use this service to allow software running in a virtual machine to call APIs provided by the virtual device.

Parameter	Description

RefData	Points to reference data to be passed to the callback procedure.

Callback	Points to the callback procedure to install. See the Comments section for more information about the procedure.

Returns

If the carry flag is clear, the EAX register contains the address of the callback procedure. Otherwise, the carry flag is set to indicate that the callback procedure could not be installed.

Comments

The system calls the callback procedure as follows:

mov     ebx, VM                 ; current VM handle

mov     edx, OFFSET32 RefData   ; points to reference data

mov     ebp, OFFSET32 crs       ; points to Client_Reg_Struc

call    [Callback]

The VM parameter is a handle identifying the current virtual machine. The RefData parameter points to the reference data supplied when the callback procedure was installed, and crs points to a Client_Reg_Struc structure containing the register values for the virtual machine.

Uses

EAX, Flags

See Also

Allocate_PM_Call_Back


Allocate_PM_Call_Back
include vmm.inc

mov     edx, OFFSET32 RefData   ; reference data (any doubleword)

mov     esi, OFFSET32 Callback  ; callback procedure to call

VMMcall Allocate_PM_Call_Back

jc      error

mov     [CallbackAddr], eax     ; selector:offset for callback

The Allocate_PM_Call_Back service installs a callback procedure that protected-mode applications can call to execute code in a virtual device. The service returns a callback address, specified as selector:offset pair. When protected-mode applications call this address, the system passes control to the callback procedure specified by the Callback parameter.

Virtual devices typically use this service to allow software running in a virtual machine to call APIs provided by the virtual device.

Parameter	Description

RefData	Points to reference data to be passed to the callback procedure.

Callback	Points to the callback procedure to install. See the Comments section for more information about the procedure.

Returns

If the carry flag is clear, the EAX register contains the address of the callback procedure. Otherwise, the carry flag is set to indicate that the callback procedure could not be installed.

Comments

The system calls the callback procedure as follows:

mov     ebx, VM                 ; current VM handle

mov     edx, OFFSET32 RefData   ; points to reference data

mov     ebp, OFFSET32 crs       ; points to Client_Reg_Struc

call    [Callback]

The VM parameter is a handle identifying the current virtual machine. The RefData parameter points to the reference data supplied when the callback procedure was installed, and crs points to a Client_Reg_Struc structure containing the register values for the virtual machine.

Uses

EAX, Flags

See Also

Allocate_V86_Call_Back


Call_When_VM_Returns
include vmm.inc

mov     eax, TimeOut            ; milliseconds until time out

mov     edx, OFFSET32 RefData   ; points to reference data

mov     esi, OFFSET32 Callback  ; points to callback procedure to install

VMMcall Call_When_VM_Returns

The Call_When_VM_Returns service installs a callback procedure that receives control when a virtual machine executes the iret instruction for the current interrupt.

Parameter	Description

TimeOut	Specifies the number of milliseconds to wait before calling the callback procedure. The time-out occurs only if the iret instruction is not executed before the specified time elapses. If this parameter is positive, the system calls the callback when time elapses. If this parameter is negative, the system calls the callback when time elapses and calls it again when the iret instruction is executed. If this parameter is zero, the system ignores the time-out.

RefData	Points to reference data to be passed to the callback procedure.

Callback	Points to the callback procedure to install. See the Comments section for more information about this procedure.

Returns

This service has no return value.

Comments

A virtual device typically uses this service in a callback procedure that it installed using the Hook_V86_Int_Chain service. This service directs the system to replace the return address for the interrupt with the address of the callback procedure. That is, the system pushes the callback procedure address on the stack when it creates the stack frame for the interrupt. The system then passes the interrupt to the virtual machine.

When the virtual machine executes the iret instruction, the callback procedure receives control and can carry out tasks. After the callback procedure returns, the system restores the original interrupt return address and execution continues as if returning from the interrupt.

The system calls this callback procedure as follows:

mov     ebx, VM                 ; current VM handle

mov     edx, OFFSET32 RefData   ; points to reference data

mov     ebp, OFFSET32 crs       ; points to a Client_Reg_Struc

call    [Callback]

The VM parameter is a handle identifying the current virtual machine. The RefData parameter points to the reference data supplied when the callback procedure was installed, and crs points to a Client_Reg_Struc structure containing the register values for the virtual machine.

If the system calls the callback procedure as a result of a time-out, it sets the carry flag before calling the procedure. If the system calls the callback a second time (once for a time-out and once for the iret instruction), the system sets the zero flag before calling the procedure.

Uses

Client_CS, Client_EIP, Flags

See Also

Hook_V86_Int_Chain


Install_V86_Break_Point
include vmm.inc

mov     eax, BreakAddr           ; break point address

mov     edx, OFFSET32 RefData    ; points to reference data

mov     esi, OFFSET32 Callback   ; points to callback procedure to install

VMMcall Install_V86_Break_Point

jc      not_installed

The Install_V86_Break_Point service inserts a break point in V86 memory of the current virtual machine and installs a break-point callback procedure to receive control when the break point occurs. A virtual device, such as the virtual MS-DOS manager, can use this service to place patches in the BIOS.

Parameter	Description

BreakAddr	Specifies the V86 address to place the break point. The address must be specified as a segment:offset pair and must specify RAM. Once installed, the break point must not be moved.

RefData	Points to reference data to be passed to the callback procedure.

Callback	Points to the callback procedure to install. See the Comments section for more information about this procedure.

Returns

The carry flag is clear if the service is successful. Otherwise, the carry flag is set to indicate an error.

Comments

Virtual devices typically place V86 break points in global virtual device memory during device initialization. For example, the XMS driver in the virtual V86MMGR device inserts a breakpoint in the real-mode XMS driver during device initialization. Thereafter, all calls to the real-mode XMS driver are intercepted by the virtual XMS driver.

The segment address specified when installing a V86 break point must be the segment address in the CS register when the virtual machine executes the break point. For example, if the break point is placed at 0100:0000 but the virtual machine executes the break point at the address 00FF:0010h, an error occurs even though the virtual machine executed a valid break point.

When the virtual machine executes the break point, the system calls the callback procedure as follows:

mov     eax, BreakAddr          ; address of breakpoint

mov     ebx, VM                 ; current VM handle

mov     edx, OFFSET32 RefData   ; points to reference data

mov     esi, BreakLinAddr       ; linear address of break point

mov     ebp, OFFSET32 crs       ; points to a Client_Reg_Struc

The BreakAddr parameter is the V86 address of the break point. VM is a handle identifying the current virtual machine and RefData points to the reference data specified when the callback procedure was installed. The BreakLinAddr parameter specified the linear address of the break point and crs points to a Client_Reg_Struc structure containing the register values for the specified virtual machine.

The Client_CS and Client_IP registers contain the address of the break point. The virtual device must change these registers to prevent the break point from being executed again when the virtual machine resumes. A virtual device can change the register by simulating the instruction that was patched, incrementing the Client_IP register past the patch, jumping to another address using the Simulate_Far_Jmp service, or returning from an interrupt handler using the Simulate_Iret service.

When the virtual device receives the System_Exit message, it must remove any break point that it placed in global V86 code, that is, code loaded before Windows was loaded. The virtual device can remove a V86 break point using the Remove_V86_Break_Point service.

Uses

Flags

See Also

Remove_V86_Break_Point


Remove_V86_Break_Point
include vmm.inc

mov     eax, BreakAddr        ; V86 address of break point

VMMcall Remove_V86_Break_Point

The Remove_V86_Break_Point service removes a V86 break point that was installed using the Install_V86_Break_Point service. It restores the original contents of the memory automatically.

Parameter	Description

BreakAddr	Specifies the address of the break point to remove. The address must be a segment:offset pair.

Returns

The carry flag is clear if the service is successful. Otherwise, the carry flag is set to indicate an error such as an invalid break point address.

Uses

Flags

See Also

Install_V86_Break_Point


Debugging Services

Clear_Mono_Screen	Clears the secondary display

Debug_Convert_Hex_Binary	Converts hexadecimal to a binary

Debug_Convert_Hex_Decimal	Converts a number to decimal

Debug_Test_Cur_VM	Checks for current virtual machine

Debug_Test_Valid_Handle	Checks for valid handle

Disable_Touch_1st_Meg	Disables the first megabyte of memory

Enable_Touch_1st_Meg	Enables the first megabyte of memory

Get_Debug_Options	Checks for command-line debugging options

Get_Mono_Chr	Gets character/attribute from secondary display

Get_Mono_Cur_Pos	Gets cursor position from secondary display

In_Debug_Chr	Reads debugging character

Is_Debug_Chr	Checks for debugging character

Log_Proc_Call	Logs the caller of the current service

Out_Debug_Chr	Writes debugging character

Out_Debug_String	Writes a string to the debugging device

Out_Mono_Chr	Writes to the secondary display

Out_Mono_String	Writes a string to the secondary display

Queue_Debug_String	Queues a debugging string

Set_Mono_Cur_Pos	Sets cursor position for secondary display

Test_Reenter	Test whether VMM has been reentered

Validate_Client_Ptr	Validates the client register pointer


Clear_Mono_Screen
include vmm.inc

VMMcall Clear_Mono_Screen

The Clear_Mono_Screen service clears the secondary display screen by filling it with spaces, and setting character attributes to normal.

This service has no parameters.

Returns

This service has no return value.

Comments

This service has no effect in the retail version of Windows. It is intended to be used with the debugging version.

Uses

Flags

See Also

Out_Mono_Chr


Debug_Convert_Hex_Binary
include vmm.inc

mov     al, Number              ; number to convert

VMMcall Debug_Convert_Hex_Binary

mov     [BinNum], eax           ; binary number

The Debug_Convert_Hex_Binary service converts an 8-bit value to a 32-bit value representing a binary number. The new value actually consists of eight 4-bit values with each value being either 0 or 1.

Parameter	Description

Number	Specifies the number to convert.

Returns

The EAX register contains the converted number.

Comments

This service is typically used in conjunction with the Trace_Out macro to display values in binary notation.

Uses

EAX

See Also

Debug_Convert_Hex_Decimal, Trace_Out


Debug_Convert_Hex_Decimal
include vmm.inc

mov     al, Number              ; number to convert

VMMcall Debug_Convert_Hex_Decimal

mov     [BinNum], eax           ; binary number

The Debug_Convert_Hex_Decimal service converts an 8-bit value to a 32-bit value representing a decimal number. The new value actually consists of eight 4-bit values, each value being in the range 0 through 9.

Parameter	Description

Number	Specifies the number to convert.

Returns

The EAX register contains the converted number.

Comments

This service is typically used in conjunction with the Trace_Out macro to display values in decimal notation.

Uses

EAX

See Also

Debug_Convert_Hex_Binary, Trace_Out


Debug_Test_Cur_VM
include vmm.inc

mov     ebx, VM         ; VM handle to check

VMMcall Debug_Test_Cur_VM

The Debug_Test_Cur_VM service determines whether the specified virtual machine is also the current virtual machine. The service crashes the current virtual machine if the VM parameter does not identify the current virtual machine handle.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to check.

Returns

This service has no return value.

Comments

This service does not return is the handle is not valid.

See Also

Crash_Cur_VM


Debug_Test_Valid_Handle
include vmm.inc

mov     ebx, VM       ; VM handle to validate

VMMcall Debug_Test_Valid_Handle

The Debug_Test_Valid_Handle service determines whether the specified virtual machine handle is valid.

This service is only available in the debugging version of Windows.

Parameter	Description

VM	Specifies the virtual machine handle to check.

Returns

This service has no return value.

Comments

This service does not return is the handle is not valid.

Virtual devices usually call this service by using the Assert_VM_Handle macro.

See Also

Assert_VM_Handle


Disable_Touch_1st_Meg
include vmm.inc

VMMcall Disable_Touch_1st_Meg

The Disable_Touch_1st_Meg service disables the first 1 megabyte of memory for the current virtual machine.

This is an asynchronous service.

This service has no parameters.

Returns

This service has no return value.

Comments

If the debugging version is not present, this service returns immediately.

Virtual devices normally call this service by using the End_Touch_1st_Meg macro.

See Also

Enable_Touch_1st_Meg


Enable_Touch_1st_Meg
include vmm.inc

VMMcall Enable_Touch_1st_Meg

The Enable_Touch_1st_Meg service enables the first 1 megabyte of memory for the current virtual machine. The service sets the present bit for the first page directory allowing a virtual device to access addresses in the range.

This is an asynchronous service but is only available in the debugging version of Windows.

This service has no parameters.

Returns

This service has no return value.

Comments

Virtual devices normally call this service by using the Begin_Touch_1st_Meg macro.

If the debugging version is not present, this service returns immediately.

See Also

Begin_Touch_1st_Meg, Disable_Touch_1st_Meg


Get_Debug_Options
include vmm.inc

mov     al, Char            ; debugging option

VMMcall Get_Debug_Options

The Get_Debug_Options service sets the zero flag if the given character was specified as a command-line debugging option when Windows was started.

This service is available during initialization only.

Parameter	Description

Char	Specifies the debugging option to check for.

Returns

If the zero flag is set, the character was specified on the command line.

Comments

This service has no effect in the retail version of Windows. It is intended to be used with the debugging version.

Uses

Flags

See Also

Test_Debug_Installed


Get_Mono_Chr
include vmm.inc

VMMcall Get_Mono_Chr

mov     byte ptr [Char], al         ; character value

mov     byte ptr [Attr], ah         ; character attribute

The Get_Mono_Chr service retrieves the character and attribute value at the current cursor position.

This service has no parameters.

Returns

The AL register contains the character value, and the AH register contains the character attribute.

Comments

This service has no effect in the retail version of Windows. It is intended to be used with the debugging version.

Uses

EAX, Flags

See Also

Out_Mono_Chr, Set_Mono_Cur_Pos


Get_Mono_Cur_Pos
include vmm.inc

VMMcall Get_Mono_Cur_Pos

mov     byte ptr [Column], dl         ; current column position

mov     byte ptr [Row], dh            ; current row position

The Get_Mono_Cur_Pos service retrieves the current cursor position for the secondary display.

This service has no parameters.

Returns

The DL register contains the column position value, and the AH register contains the row position.

Comments

This service has no effect in the retail version of Windows. It is intended to be used with the debugging version.

Uses

Flags

See Also

Set_Mono_Cur_Pos


In_Debug_Chr
include vmm.inc

VMMcall In_Debug_Chr

mov     byte ptr [Char], al     ; character from debug device

The In_Debug_Chr service reads a character from the debugging device.

This service has no parameters.

Returns

The AL register contains the character read. If the ESCAPE key or CTRL+C key combination was pressed, the service sets the zero flag.

Comments

This service has no effect in the retail version of Windows. It is intended to be used with the debugging version.

Uses

EAX

See Also

Is_Debug_Chr


Is_Debug_Chr
include vmm.inc

VMMcall Is_Debug_Chr

jz      no_character            ; Z set if no character available

mov     byte ptr [Char], al     ; character from debugging device

The Is_Debug_Chr service checks for a character from the debugging device.

This service has no parameters.

Returns

If the zero flag is clear, the AL register contains the character from the debugging device. The zero flag is set if no character is available.

Comments

This service has no effect in the retail version of Windows. It is intended to be used with the debugging version.

Uses

EAX, Flags

See Also

In_Debug_Chr


Log_Proc_Call
include vmm.inc

VMMcall Log_Proc_Call

The Log_Proc_Call service creates a debugging message that identifies which service or virtual device called the service that called Log_Proc_Call. This service is intended to be used only for debugging and creates the message only if the user has turned on call logging.

This is an asynchronous service.

This service has no parameters.

Returns

This service has no return value.

Comments

When the BeginProc macro creates a new service, the macro generates a call to Log_Proc_Call if the DEBUG symbol is defined and the NO_LOG attribute is not specified as a parameter to BeginProc.

The service adds the message to the debugging queue using the Queue_Out macro.

See Also

BeginProc, Queue_Out


Out_Debug_Chr
include vmm.inc

mov     al, Char        ; character to write

VMMcall Out_Debug_Chr

The Out_Debug_Chr service writes a character to the debugging device.

Parameter	Description

Char	Specifies the character to write to the debugging device.

Returns

This service has no return value.

Comments

This service has no effect in the retail version of Windows. It is intended to be used with the debugging version.

Uses

EAX

See Also

Out_Debug_String


Out_Debug_String
include vmm.inc

pushfd                              ; save flags on stack

pushad                              ; save registers on stack

mov     esi, OFFSET32 String        ; points to string to write

VMMcall Out_Debug_String

popad

popfd

The Out_Debug_String service writes the specified null-terminated string to the debugging device (the COM1 serial port). If the string contains register placeholders, Out_Debug_String replaces these with the actual register values (in hexadecimal), or the symbolic label nearest to the specified addresses.

Parameter	Description

String	Points to a null-terminated string specifying the message to write to the debugging device. Out_Debug_String uses the lods instruction to process characters in the string, so the DS register must specify the correct segment selector for the string.

The string can contain one or more placeholders having the following forms:

Placeholder	Description

#register	Displays the current value of the specified register. For example, the service replaces #AX with the value of the AX register. The register must not be the name of a segment register.

?register	Displays the label nearest the address specified by the registers. For example, the service replaces ?EAX with the VMM code segment label nearest the address in the EAX register. The register must not be the name of a segment register.

?register:register	Displays the label nearest the address specified by the registers. For example, the service replaces ?AX:EBX with the label in the segment specified by the AX register that is nearest to the address in the EBX register. The register must not be the name of a segment register.

Returns

This service has no return value.

Comments

This service has no effect in the retail version of Windows. It is intended to be used with the debugging version.

If the string contains placeholders, Out_Debug_String requires the caller to use the pushfd and pushad instructions before carrying out a near call to this service.

Uses

All registers and flags

See Also

Trace_Out


Out_Mono_Chr
include vmm.inc

mov     al, Char        ; character to write

VMMcall Out_Mono_Chr

mov     eax, 0          ; write character and attribute

mov     bl, Char        ; character to write

mov     bh, Attr        ; attribute to write

VMMcall Out_Mono_Chr

The Out_Mono_Chr service writes a character to the current position on the secondary display.

If the EAX register is not zero, the service writes the character in the AL register and applies the normal attribute. Otherwise, it writes the character and attribute pair in the BX register.

Parameter	Description

Char	Specifies the character to write to the secondary display.

Attr	Specifies the attribute to apply to the character when written.

Returns

This service has no return value.

Comments

If the linefeed or carriage return character is written, the service automatically adjusts the cursor position, scrolling the screen if necessary.

This service has no effect in the retail version of Windows. It is intended to be used with the debugging version.

Uses

Flags

See Also

Out_Mono_String


Out_Mono_String
include vmm.inc

mov     esi, OFFSET32 String        ; points to string to write

VMMcall Out_Mono_String

The Out_Mono_String service writes the specified null-terminated string to the secondary display. If the string contains register placeholders, Out_Mono_String replaces these with the actual register values (in hexadecimal), or the symbolic label nearest to the specified addresses.

Parameter	Description

String	Points to a null-terminated string specifying the message to write to the debugging device. Out_Mono_String uses the lods instruction to process characters in the string, so the DS register must specify the correct segment selector for the string.

The string can contain one or more placeholders having the following forms:

Placeholder	Description

#register	Displays the current value of the specified register. For example, the service replaces #AX with the value of the AX register. The register must not be the name of a segment register.

?register	Displays the label nearest the address specified by the registers. For example, the service replaces ?EAX with the VMM code segment label nearest the address in the EAX register. The register must not be the name of a segment register.

?register:register	Displays the label nearest the address specified by the registers. For example, the service replaces ?AX:EBX with the label in the segment specified by the AX register that is nearest to the address in the EBX register. The register must not be the name of a segment register.

Returns

This service has no return value.

Comments

This service has no effect in the retail version of Windows. It is intended to be used with the debugging version.

Uses

All registers and flags

See Also

Mono_Out, Out_Debug_String


Queue_Debug_String
include vmm.inc

mov     eax, Value1             ; value for string

push    eax

mov     eax, Value2             ; value for string

push    eax

mov     esi, OFFSET32 String    ; points to string to queue

VMMcall Queue_Debug_String

The Queue_Debug_String service queues a string and corresponding values for display at a later time. The message remains queued until the user enters the .LQ command using the debugger.

Parameter	Description

Value1	Specifies a value to queue with the string. If the string contains the #EAX or ?EAX placeholder, this value is used when the string is displayed.

Value2	Specifies a value to queue with the string. If the string contains the #EBX or ?EBX placeholder, this value is used when the string is displayed.

String	Points to a null-terminated string to queue. It can contain one or more of the following register placeholders: #AX, #EAX, ?EAX, #BX, #EBX, ?EBX, ?AX:EBX, ?BX:EAX.

Returns

This service has no return value.

Comments

This service has no effect in the retail version of Windows. It is intended to be used with the debugging version.

Uses

Flags

See Also

Out_Debug_String


Set_Mono_Cur_Pos
include vmm.inc

mov     dl, Column      ; current column position

mov     dh, Row         ; current row position

VMMcall Set_Mono_Cur_Pos

The Set_Mono_Cur_Pos service sets the current cursor position for the secondary display.

Parameter	Description

Column	Specifies the column position.

Row	Specifies the row position.

Returns

This service has no return value.

Comments

This service has no effect in the retail version of Windows. It is intended to be used with the debugging version.

Uses

Flags

See Also

Get_Mono_Cur_Pos


Test_Reenter
include vmm.inc

VMMcall Test_Reenter

The Test_Reenter service checks the re-entry count for the VMM and values of the DS, ES, and SS registers. If the re-entry count is not zero or the segment registers are not equal to the VMM's data segment selector, the service display an error message at the debugging terminal. This service is intended to be used only for debugging.

This is an asynchronous service.

This service has no parameters.

Returns

This service has no return value.

Comments

When the BeginProc macro creates a new service, the macro generates a call to Test_Reenter if the SERVICE attribute is specified with BeginProc and the DEBUG symbol is defined.

See Also

BeginProc


Validate_Client_Ptr
include vmm.inc

mov     ebp, OFFSET32 crs       ; points to a Client_Reg_Struc

VMMcall Validate_Client_Ptr

The Validate_Client_Ptr service determines whether the address specified by crs points to the Client_Reg_Struc structure for the current virtual machine. If the address is not correct, the service crashes the current virtual machine.

This is an asynchronous service.

Parameter	Description

crs	Points to the Client_Reg_Struc structure to check.

Returns

This service has no return value.

Comments

This service never returns if the client register pointer is not valid.

If the current re-entry count for the VMM is not zero, this service returns immediately without checking the client register pointer.


Error Handling Services

Crash_Cur_VM	Terminates the current VM

Fatal_Error_Handler	Terminates Windows

Fatal_Memory_Error	Terminates Windows


Crash_Cur_VM
include vmm.inc

VMMcall Crash_Cur_VM

The Crash_Cur_VM service abruptly terminates the current VM. A virtual device should call this service when a catastrophic error has occured in the VM, such as executing an illegal instruction or attempting to program a piece of hardware in a way incompatible with the device virtualization.

If the system VM is the current VM, Windows exits with a fatal error without explicitly crashing the other VMs.

Parameter	Description

This service has no parameters.

Returns

This service does not return


Fatal_Error_Handler
include vmm.inc

mov     esi, <MsgPtr>       ; points to message to display

mov     eax, <ErrFlags>     ; exit flags

VMMcall Fatal_Error_Handler

The Fatal_Error_Handler service terminates Windows by informing all initialized virtual devices that is an unrecoverable error has occurred and returning to real mode (optionally printing an error message). A virtual device should call or jump to this service when it detects a fatal error.

Parameter	Description

MsgPtr	Points to a zero-terminated string specifying the message to display. If this parameter is 0, no message is displayed.

ErrFlags	Specifies the exit flags. It can be a combination of the following values:

Value	Meaning

EF_Hang_On_Exit	Hangs the system on a fatal exit.

All other values are reserved.

Returns

This service does not return.

Uses

All registers

See Also

Fatal_Error, Fatal_Memory_Error


Fatal_Memory_Error
include vmm.inc

VMMcall Fatal_Memory_Error

The Fatal_Memory_Error service terminates Windows and displays an error message indicating that there was not enough memory to initialize one or more virtual devices. A virtual device should call this service during intialization if there is not enough memory to initialize.

This service has no parameters

Returns

This service does not return.

Comments

This service uses the Fatal_Error_Handler service to terminate Windows. Fatal_Memory_Error sets the exit flags to zero before calling the Fatal_Error_Handler.

Uses

All registers

See Also

Fatal_Error_Handler


Event Services

Call_Global_Event	Calls the event procedure or schedules an event

Call_Priority_VM_Event	Schedules a priority event

Call_VM_Event	Schedules an event for a virtual machine

Cancel_Global_Event	Cancels a global event

Cancel_Priority_VM_Event	Cancels a priority event

Cancel_VM_Event	Cancels an event for a virtual machine

Schedule_Global_Event	Schedules a global event

Schedule_VM_Event	Schedule an event for a virtual machine


Call_Global_Event
include vmm.inc

mov     esi, OFFSET32 EventCallback ; points to callback procedure

mov     edx, OFFSET32 RefData       ; points to reference data

VMMcall Call_Global_Event

mov     [Event], esi                ; event handle or zero if not scheduled

The Call_Global_Event service either calls the event callback procedure immediately, or schedules a global event. This service schedules the event if the virtual device is processing a hardware interrupt that interrupted the VMM. In all other cases, the service calls the callback procedure without scheduling an event.

This is an asynchronous service.

Parameter	Description

EventCallback	Points to the callback procedure. See the Comments section for more information about the procedure.

RefData	Points to reference data to be passed to the event callback procedure.

Returns

The ESI register is zero if the service calls the callback procedure. Otherwise, the ESI register contains the event handle. The event handle can be used in subsequent calls to the Cancel_Global_Event service to cancel the event.

Comments

If the service schedules a global event, the system calls the event callback procedure immediately before the returning from the current interrupt. Any virtual machine can process the event, so the system does not switch tasks before calling the procedure.

The callback procedure can carry out any actions, and use any VMM services. The system calls the event callback procedure as follows:

mov     ebx, VM                 ; current VM handle

mov     edx, OFFSET32 RefData   ; points to reference data

mov     ebp, OFFSET32 crs       ; points to a Client_Reg_Struc

call    [EventCallback]

The VM parameter is a handle identifying the current virtual machine, RefData points to reference data supplied by the virtual machine that scheduled the event, and crs points to a Client_Reg_Struc structure containing the contents of the virtual machine's registers.

The callback procedure can modify EAX, EBX, ECX, EDX, ESI, and EDI.

Uses

Flags

See Also

Cancel_Global_Event, Schedule_Global_Event


Call_Priority_VM_Event
include vmm.inc

mov     eax, PriorityBoost          ; priority boost (can be 0)

mov     ebx, VM                     ; VM handle

mov     ecx, Flags                  ; option flags

mov     edx, OFFSET32 RefData       ; points to reference data

mov     esi, OFFSET32 EventCallback ; points to event callback procedure

mov     edi, TimeOut                ; number of milliseconds for time-out

VMMcall Call_Priority_VM_Event

mov     [Event], esi            ; event handle or zero if callback called

The Call_Priority_VM_Event service either calls the callback procedure immediately or schedules a priority event for the specified virtual machine. This service schedules the event if the virtual device is processing a hardware interrupt that interrupted the VMM, or the current virtual machine is not the specified virtual machine, or the Flags parameter specifies the PEF_Always_Sched value. In all other cases, the service calls the callback procedure and returns without scheduling an event.

This is an asynchronous service.

Parameter	Description

PriorityBoost	Specifies a positive or negative priority boost for the virtual machine. This parameter must be a value such that when added to the current execution priority the result is within the range Reserved_Low_Boost to Reserved_High_Boost. This parameter can be 0 if no boost is necessary.

The following lists some common priority boost values:

Value	Meaning

Reserved_Low_Boost	Reserved for use by system.

Cur_Run_VM_Boost	The time-slice scheduler uses this value to force a virtual machine to run for its allotted time-slice.

Low_Pri_Device_Boost	Virtual devices use this value for events that need timely processing, but are not time critical.

High_Pri_Device_Boost	Virtual devices use this value for events that need timely processing, but should not circumvent operations that have a critical section boost.

Critical_Section_Boost	The system uses this value for virtual machines specified in a call to the Begin_Critical_Section service.

Time_Critical_Boost	Virtual devices use this value for events that must be processed even when another virtual machine is in a critical section. For example, VPICD uses this when simulating hardware interrupts.

Reserved_High_Boost	Reserved for use by system.

VM	Specifies a handle identifying the virtual machine to process the event.

Flags	Specifies how to carry out the event. This parameter can be a combination of the following values:

Value	Meaning

PEF_Wait_For_STI	Callback procedure is not called until the virtual machine enables interrupts.

PEF_Wait_Not_Crit	Callback procedure is not called until the virtual machine is not in a critical section or time-critical operation.

PEF_Dont_Unboost	Priority of the virtual machine is not reduced after return from callback procedure.

PEF_Always_Sched	Event is always scheduled, meaning the callback procedure is never called immediately.

PEF_Time_Out	Specifies that time-out value in the EDI register should be used. Available in Windows version 3.1 or later.

All other values are reserved.

RefData	Points to reference data to be passed to the callback procedure.

EventCallback	Points to the callback procedure. See the Comments section for more information about the procedure.

TimeOut	Specifies the number of milliseconds until the event times out. The service uses this parameter only if the PEF_Time_Out value is specified by the Flags parameter.

Returns

The ESI register is zero if the callback procedure was called immediately. Otherwise, the ESI register contains the event handle. The handle can be used in a subsequent call to the Cancel_Priority_VM_Event service to cancel the event.

Comments

The system carries out a task switch to the specified virtual machine if it is not the current virtual machine. If the PriorityBoost parameter is not zero, the service boosts the priority of the virtual machine before calling the callback procedure.

If the amount of time specified by the TimeOut parameter elapses before the system can switch to the virtual machine, the system sets the carry flag and calls the callback procedure immediately regardless of which virtual machine is currently running. In this case, any requested priority boost is canceled even if the Flags parameter specified the PEF_Dont_Unboost value. The callback procedure should always check the carry flag to determine whether a time out occurred.

The callback procedure can carry out any actions and use any VMM services. The system calls the event callback procedure as follows:

mov     ebx, VM                 ; current VM handle

mov     edx, OFFSET32 RefData   ; points to reference data

mov     ebp, OFFSET32 crs       ; points to a Client_Reg_Struc

call    [EventCallback]

The VM parameter is a handle identifying the current virtual machine. If a time-out occurred, this handle may not be valid. In such cases, the callback procedure should use the Get_Cur_VM_Handle service to get the handle of the current virtual machine.

The RefData parameter points to reference data supplied by the virtual machine that scheduled the event and crs points to a Client_Reg_Struc structure containing the contents of the current virtual machine's registers.

The callback procedure can modify EAX, EBX, ECX, EDX, ESI, EDI, and Flags.

Uses

Flags

See Also

Adjust_Exec_Priority, Call_VM_Event, Call_When_Not_Critical, Call_When_VM_Ints_Enabled,Cancel_Priority_VM_Event


Call_VM_Event
include vmm.inc

mov     ebx, VM                     ; VM handle

mov     esi, OFFSET32 EventCallback ; points to callback procedure

mov     edx, OFFSET32 RefData       ; points to reference data

VMMcall Call_VM_Event

mov     [Event], esi                ; event handle or zero if not scheduled

The Call_VM_Event service either calls the event callback procedure immediately, or schedules an event for the specified virtual machine. This service schedules the event if the virtual device is processing a hardware interrupt that interrupted the VMM, or the current virtual machine is not the specified virtual machine. In all other cases, the service calls the callback procedure and returns without scheduling an event.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to process the event.

EventCallback	Points to the callback procedure. See the Comments section for more information about the procedure.

RefData	Points to reference data to be passed to the event callback procedure.

Returns

The ESI register is zero if the service calls the callback procedure. Otherwise, the ESI register contains the event handle. The event handle can be used in subsequent calls to the Cancel_VM_Event service to cancel the event.

This is an asynchronous service.

Comments

Since the specified virtual machine must process the event, the system carries out a task switch if necessary before calling the procedure. The callback procedure can carry out any actions and use any VMM services. The system calls the event callback procedure as follows:

mov     ebx, VM                 ; current VM handle

mov     edx, OFFSET32 RefData   ; points to reference data

mov     ebp, OFFSET32 crs       ; points to a Client_Reg_Struc

call    [EventCallback]

The VM parameter is a handle identifying the current virtual machine, RefData points to reference data supplied by the virtual machine that scheduled the event, and crs points to a Client_Reg_Struc structure containing the contents of the virtual machine's registers.

The callback procedure can modify EAX, EBX, ECX, EDX, ESI, and EDI.

Uses

Flags

See Also

Cancel_VM_Event, Schedule_VM_Event


Cancel_Global_Event
include vmm.inc

mov     esi, Event          ; event handle

VMMcall Cancel_Global_Event

The Cancel_Global_Event service cancels an event that was previously scheduled using the Schedule_Global_Event or Call_Global_Event service. A virtual device must not attempt to cancel an event if the callback procedure for the event has already been called.

Parameter	Description

Event	Specifies a handle identifying the event to cancel. This parameter can be zero to indicate that no event should be canceled.

Returns

This service has no return value.

Comments

The event callback procedure typically sets the event handle to zero so that subsequent calls by the virtual machine to this service do not cause errors.

See Also

Call_Global_Event, Schedule_Global_Event


Cancel_Priority_VM_Event
include vmm.inc

mov     esi, Event              ; priority event handle

VMMcall Cancel_Priority_VM_Event

The Cancel_Priority_VM_Event service cancels an event that was previously scheduled using the Call_Priority_VM_Event service. A virtual device must not attempt to cancel an event if the callback procedure for the event has already been called.

Parameter	Description

Event	Specifies a handle identifying the event to cancel. This parameter can be zero to indicate that no event should be canceled.

Returns

This service has no return value.

Comments

The event callback procedure typically sets the event handle to zero so that subsequent calls by the virtual machine to this service do not cause errors.

This service cancels any priority boost associated with the event even if the PEF_Dont_Unboost value was specified when the event was scheduled.

Do not use this service to cancel events scheduled using the Call_VM_Event or Schedule_VM_Event services. You must cancel virtual machine events using the Cancel_VM_Event service.

Uses

Flags, ESI

See Also

Call_Priority_VM_Event


Cancel_VM_Event
include vmm.inc

mov     ebx, VM        ; VM handle

mov     esi, Event     ; event handle

VMMcall Cancel_VM_Event

The Cancel_VM_Event service cancels an event that was previously scheduled using the Schedule_VM_Event or Call_VM_Event service. A virtual device must not attempt to cancel an event if the callback procedure for the event has already been called.

Parameter	Description

VM	Specifies a handle identifying the virtual machine for which the event is to be canceled.

Event	Specifies a handle identifying the event to cancel. This parameter can be zero to indicate that no event should be canceled.

Returns

This service has no return value.

Comments

The event callback procedure typically sets the event handle to zero so that subsequent calls by the virtual machine to this service do not cause errors.

Do not use this service to cancel events scheduled using the Call_Priority_VM_Event service. You must cancel priority events using the Cancel_Priority_VM_Event service.

Uses

Flags

See Also

Call_VM_Event, Schedule_VM_Event


Schedule_Global_Event
include vmm.inc

mov     esi, OFFSET32 EventCallback ; points to callback procedure

mov     edx, OFFSET32 RefData       ; points to reference data

VMMcall Schedule_Global_Event

mov     [Event], esi                ; event handle

The Schedule_Global_Event service schedules a global event, which is an event that does not require a specific virtual machine to process it. The system calls the event callback procedure immediately before the returning from the current interrupt. Since any virtual machine can process the event, the system does not switch tasks before calling the procedure.

This is an asynchronous service.

Parameter	Description

EventCallback	Points to the callback procedure. See the Comments section for more information about the procedure.

RefData	Points to reference data to be passed to the event callback procedure.

Returns

The ESI register contains the event handle. The handle can be used in a subsequent call to the Cancel_Global_Event service to cancel the event.

Comments

The callback procedure can carry out any actions and use any VMM services. The system calls the event callback procedure as follows:

mov     ebx, VM                 ; current VM handle

mov     edx, OFFSET32 RefData   ; points to reference data

mov     ebp, OFFSET32 crs       ; points to a Client_Reg_Struc

call    [EventCallback]

The VM parameter is a handle identifying the current virtual machine, RefData points to reference data supplied by the virtual machine that scheduled the event, and crs points to a Client_Reg_Struc structure containing the contents of the virtual machine's registers.

The callback procedure can modify EAX, EBX, ECX, EDX, ESI, and EDI.

See Also

Call_Global_Event, Cancel_Global_Event


Schedule_VM_Event
include vmm.inc

mov     ebx, VM                     ; VM handle

mov     esi, OFFSET32 EventCallback ; points to callback procedure

mov     edx, OFFSET32 RefData       ; points to reference data

VMMcall Schedule_VM_Event

mov     [Event], esi                ; event handle

The Schedule_VM_Event service schedules an event for the specified virtual machine. Since the event must be processed by the specified virtual machine, the system carries out a task switch to the virtual machine (if necessary) before calling the event callback procedure. The system completes the event processing before the VMM returns from the current interrupt.

This is an asynchronous service.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to process the event.

EventCallback	Points to the callback procedure. See the Comments section for more information about the procedure.

RefData	Points to reference data to be passed to the event callback procedure.

Returns

The ESI register contains the event handle. The event handle can be used in subsequent calls to the Cancel_VM_Event service to cancel the event.

Comments

Since the specified virtual machine must process the event, the system carries out a task switch if necessary before calling the procedure. The callback procedure can carry out any actions and use any VMM services. The system calls the event callback procedure as follows:

mov     ebx, VM                 ; current VM handle

mov     edx, OFFSET32 RefData   ; points to reference data

mov     ebp, OFFSET32 crs       ; points to a Client_Reg_Struc

call    [EventCallback]

The VM parameter is a handle identifying the current virtual machine, RefData points to reference data supplied by the virtual machine that scheduled the event, and crs points to a Client_Reg_Struc structure containing the contents of the virtual machine's registers.

The callback procedure can modify EAX, EBX, ECX, EDX, ESI, and EDI.

See Also

Call_VM_Event, Cancel_VM_Event


Processor Fault and Interrupt Services

Get_Fault_Hook_Addrs	Returns addresses for fault handlers

Get_NMI_Handler_Addr	Returns NMI handler address

Hook_Invalid_Page_Fault	Installs a hook procedure for page faults

Hook_NMI_Event	Installs an NMI event procedure

Hook_PM_Fault	Installs a fault handler for protected mode

Hook_V86_Fault	Installs a fault handler for V86 mode

Hook_VMM_Fault	Installs a fault handler for VMM

Set_NMI_Handler_Addr	Sets the NMI handler address

Unhook_Invalid_Page_Fault	Removes a hook procedure for page faults


Get_Fault_Hook_Addrs
include vmm.inc

mov     eax, Interrupt      ; interrupt number

VMMcall Get_Fault_Hook_Addrs

The Get_Fault_Hook_Addrs service returns addresses of the V86 mode, protected-mode, and VMM fault handlers for a specified fault.

Parameter	Description

Interrupt	Specifies the interrupt number of the fault to check.

Returns

If the carry flag is clear, the EDX, ESI, and EDI registers contain the addresses described in the following list. Otherwise, the carry flag is set to indicate an error such as an invalid interrupt number.

Register	Description

EDX	Contains the address of the fault handler installed by a V86 mode application. This register contains zero if no handler has been installed.

ESI	Contains the address of the fault handler installed by a protected-mode application. This register contains zero if no handler has been installed.

EDI	Contains the address of a fault handle installed by the VMM. This register contains zero if no handler has been installed.

Comments

A virtual device cannot get the hook address for the Non-Maskable Interrupt (Interrupt 2). It must use the Get_NMI_Handler_Addr and Set_NMI_Handler_Addr services to hook Interrupt 2.

Uses

Flags

See Also

Get_NMI_Handler_Addr, Set_NMI_Handler_Addr


Get_NMI_Handler_Addr
include vmm.inc

VMMcall Get_NMI_Handler_Addr

mov     [NMI], esi          ; offset to current NMI handler

The Get_NMI_Handler_Addr service returns the address of the current Non-Maskable Interrupt (NMI) handler.

This service has no parameters.

Returns

The ESI register contains the offset of current NMI handler.

Comments

If a virtual device needs to hook the Non-Maskable Interrupt it must first call this service to get and save the original NMI handler address. The virtual can then install the new NMI handler my using the Set_NMI_Handler_Addr service. The new handler should create an NMI handler chain by passing execution to the original NMI handler whenever it does not process the NMI.

Uses

ESI, Flags

See Also

Set_NMI_Handler_Addr


Hook_Invalid_Page_Fault
include vmm.inc

mov     esi, OFFSET32 HookProc  ; points to hook procedure to install

VMMcall Hook_Invalid_Page_Fault

jc      not_installed           ; carry set if procedure not installed

The Hook_Invalid_Page_Fault service installs a hook procedure to handle any invalid-page faults not handled by the system invalid-page-fault handler.

Parameter	Description

HookProc	Points to the hook procedure to install. See the Comments section for more information about this procedure.

Returns

The carry flag is clear if the hook procedure is installed. The carry flag is set if the procedure could not be installed.

Comments

The system enables interrupts and calls the hook procedure as follows:

mov     ebx, VM             ; current VM handle

mov     edi, OFFSET32 ipf   ; points to an IPF_Data

call    [HookProc]

jc      not_corrected       ; carry set if procedure did not correct fault

The VM parameter is a handle identifying the current virtual machine, and the ipf parameter points to an IPF_Data structure containing information about the page fault.

The procedure clears the carry flag if it handles the page fault. Otherwise, it must set the carry flag to indicate that the page fault has not been corrected. The system passes the fault to the next procedure in the chain.

The hook procedure may use all registers except the segment registers.

Uses

Flags

See Also

Unhook_Invalid_Page_Fault, IPF_Data


Hook_NMI_Event
include vmm.inc

mov     esi, OFFSET32 NmiProc   ; points to NMI event procedure

VMMcall Hook_NMI_Event

The Hook_NMI_Event service installs a Non-Maskable Interrupt (NMI) event procedure. Virtual devices use this service to install event procedures to carry out tasks that are not permitted in NMI handlers.

This service is only available during initialization.

Parameter	Description

NmiProc	Points to an NMI event procedure. See the Comments section for more information about this procedure.

Returns

This service has no return value.

Comments

The system calls each installed NMI event procedure after the last handler in the NMI handler chain has executed. If more than one NMI event procedure is installed, the system calls the procedures in the order in which they where installed. The system calls the event procedure as follows:

mov     ebx, VM              ; current VM handle

mov     ebp, OFFSET32 crs    ; points to a Client_Reg_Struc

call    [NmiProc]

The VM parameter is a handle identifying the current virtual machine, and the crs parameter points to a Client_Reg_Struc structure containing the register values for the current virtual machine.

NMI event procedures can be re-entered. This means an event procedure can be interrupted by another NMI.

Uses

Flags

See Also

Set_NMI_Handler_Addr, Client_Reg_Struc


Hook_PM_Fault
include vmm.inc

mov     eax, Interrupt          ; interrupt number for fault

mov     esi, OFFSET32 FaultProc ; points to a fault handler

VMMcall Hook_PM_Fault

jc      not_installed           ; carry set if not installed

mov     [Previous], esi         ; points to previous fault handler (if any)

The Hook_PM_Fault service installs a fault handler procedure for protected mode. Virtual devices typically install fault handlers while processing the Sys_Critical_Init control message to handle faults, such as general protection faults, that the VMM's own fault handlers cannot handle. The VMM installs its fault handlers only after the Sys_Critical_Init control message. Virtual devices install fault handlers after Sys_Critical_Init to handle faults before the fault is passed to the VMM's fault handlers.

Parameter	Description

Interrupt	Specifies the number of the interrupt for which to install the fault handler. The interrupt number cannot be 02h and must not be greater than 4Fh.

FaultProc	Points to the fault handler to install. See the Comments section for more information about this procedure.

Returns

If the carry flag is clear, the ESI register contains the address of the previous fault handler. The register contains zero if there was no previous handler.

If the carry flag is set, the specified fault number is not valid and the handler is not installed.

Comments

A virtual device can install a fault handler while processing the Sys_Critical_Init control message or at a later time. Any fault handler a virtual device may install while processing the message receives a fault only after the VMM's own fault handlers have had a chance to process the fault.

The system disables interrupts and calls the fault handler as follows:

mov     ebx, VM                 ; current VM handle

mov     ebp, OFFSET32 crs       ; points to a Client_Reg_Struc

call    [FaultProc]

The VM parameter is a handle identifying the current virtual machine, and the crs parameter points to a Client_Reg_Struc structure containing the register values for the current virtual machine.

If the fault does not process the fault, it should pass the fault to the previous fault handler (if any), making sure that all registers are preserved (not just the registers containing input parameters).

If the fault handler processes the fault or if there is no previous fault handler, the handler should return without chaining by executing a near ret instruction (not an iret instruction).

The fault handler can modify EAX, EBX, ECX, EDX, ESI, and EDI.

Do not use this service to install a fault handler for the Non-Maskable Interrupt (NMI). Instead, a virtual device must use the Get_NMI_Handler_Addr and Set_NMI_Handler_Addr services.

Do not use this service to install handlers for hardware interrupts. Instead, a virtual device must use virtual PIC device services.

Uses

ESI, Flags

See Also

Hook_V86_Fault, Hook_VMM_Fault


Hook_V86_Fault
include vmm.inc

mov     eax, Interrupt          ; interrupt number for fault

mov     esi, OFFSET32 FaultProc ; points to a fault handler

VMMcall Hook_V86_Fault

jc      not_installed           ; carry set if not installed

mov     [Previous], esi         ; points to previous fault handler (if any)

The Hook_V86_Fault service installs a fault handler procedure for V86 mode. Virtual devices typically install fault handlers while processing the Sys_Critical_Init control message to handle faults, such as general protection faults, that the VMM's own fault handlers cannot handle. The VMM installs its fault handlers after the Sys_Critical_Init control message. Virtual devices install fault handlers after Sys_Critical_Init to handle faults before the fault is passed to the VMM's fault handlers.

Parameter	Description

Interrupt	Specifies the number of the interrupt for which to install the fault handler. The interrupt number cannot be 02h and must not be greater than 4Fh.

FaultProc	Points to the fault handler to install. See the Comments section for more information about this procedure.

Returns

If the carry flag is clear, the ESI register contains the address of the previous fault handler. The register contains zero if there was no previous handler.

If the carry flag is set, the specified fault number is not valid and the handler is not installed.

Comments

A virtual device can install a fault handler while processing the Sys_Critical_Init message or at a later time. Any fault handler a virtual device may install while processing the message receives a fault only after the VMM's own fault handlers have had a chance to process the fault.

The system disables interrupts and calls the fault handler as follows:

mov     ebx, VM                 ; current VM handle

mov     ebp, OFFSET32 crs       ; points to a Client_Reg_Struc

call    [FaultProc]

The VM parameter is a handle identifying the current virtual machine, and the crs parameter points to a Client_Reg_Struc structure containing the register values for the current virtual machine.

If the fault does not process the fault, it should pass the fault to the previous fault handler (if any), making sure that all registers are preserved (not just the registers containing input parameters).

If the fault handler processes the fault or if there is no previous fault handler, the handler should return without chaining by executing a near ret instruction (not an iret instruction).

The fault handler can modify EAX, EBX, ECX, EDX, ESI, and EDI.

Do not use this service to install a fault handler for the Non-Maskable Interrupt (NMI). Instead, a virtual device must use the Get_NMI_Handler_Addr and Set_NMI_Handler_Addr services.

Do not use this service to install handlers for hardware interrupts. Instead, a virtual device must use virtual PIC device services.

Uses

ESI, Flags

See Also

Hook_PM_Fault, Hook_VMM_Fault


Hook_VMM_Fault
include vmm.inc

mov     eax, Interrupt          ; interrupt number for fault

mov     esi, OFFSET32 FaultProc ; points to a fault handler

VMMcall Hook_VMM_Fault

jc      not_installed           ; carry set if not installed

mov     [Previous], esi         ; points to previous fault handler (if any)

The Hook_VMM_Fault service installs a fault handler procedure for the VMM. Virtual devices typically install fault handlers while processing the Sys_Critical_Init control message to handle faults, such as general protection faults, that the VMM's own fault handlers cannot handle. The VMM installs its fault handlers after the Sys_Critical_Init control message. Virtual devices install fault handlers after Sys_Critical_Init to handle faults before the fault is passed to the VMM's fault handlers.

Parameter	Description

Interrupt	Specifies the number of the interrupt for which install the fault handler. The interrupt number cannot be 02h and must not be greater than 4Fh.

FaultProc	Points to the fault handler to install. See the Comments section for more information about this procedure.

Returns

If the carry flag is clear, the ESI register contains the address of the previous fault handler. The register contains zero if there was no previous handler.

If the carry flag is set, the specified fault number is not valid and the handler is not installed.

Comments

A virtual device can install a fault handler while processing the Sys_Critical_Init message or at a later time. Any fault handler a virtual device may install while processing the message receives a fault only after the VMM's own fault handlers have had a chance to process the fault.

The system disables interrupts and calls the fault handler as follows:

mov     ebx, VM                 ; current VM handle

mov     ebp, OFFSET32 stkfrm    ; points to VMM re-entrant stack frame

call    [FaultProc]

The VM parameter is a handle identifying the current virtual machine, and the stkfrm parameter points to the VMM re-entrant fault stack frame.

The fault handler may call asynchronous services only.

If the fault handler does not process the fault, it should pass the fault to the previous fault handler (if any), making sure that all registers are preserved (not just the registers containing input parameters).

If the fault handler processes the fault or if there is no previous fault handler, the handler should return without chaining by executing a near ret instruction (not an iret instruction).

The fault handler can modify EAX, EBX, ECX, EDX, ESI, and EDI.

Do not use this service to install a fault handler for the Non-Maskable Interrupt (NMI). Instead, a virtual device must use the Get_NMI_Handler_Addr and Set_NMI_Handler_Addr services.

Do not use this service to install handlers for hardware interrupts. Instead, a virtual device must use virtual PIC device services.

Uses

ESI, Flags

See Also

Hook_PM_Fault, Hook_V86_Fault


Set_NMI_Handler_Addr
include vmm.inc

mov     esi, OFFSET32 nmi       ; points to new NMI handler

VMMcall Set_NMI_Handler_Addr

The Set_NMI_Handler_Addr service sets the Non-Maskable Interrupt (NMI) vector to the address of the specified NMI handler.

Parameter	Description

nmi	Points to the new NMI handler.

Returns

This service has no return value.

Comments

To install an NMI handler, a virtual device must retrieve and save the current NMI handler address using the Get_NMI_Handler_Addr service, and set the new address using Set_NMI_Handler_Addr.

The NMI handler must not call VMM or virtual device services. This restriction includes calls to asynchronous VMM services. The NMI handler can examine and modify local data in the VxD_LOCKED_DATA_SEG segment, but it must not attempt to access any other memory, including virtual machine and V86 memory. If a virtual device needs to use VMM services in response to an NMI, it should install an NMI event handler using the Hook_NMI_Event service.

The NMI handler must not execute the iret instruction. Instead, it must jump to the address of the previous NMI handler (retrieved using the Get_NMI_Handler_Addr service). The CPU ignores additional NMIs until it executes the iret instruction. Because no NMI handlers in the chain execute this instruction, the handlers are guaranteed not to be re-entered.

Some computers require the latch at port 70h be reset to enable further NMIs. To simplify NMI processing for other NMI handlers, the virtual parity device (PARITY) automatically resets this latch.

Uses

Flags

See Also

Get_NMI_Handler_Addr, Hook_NMI_Event


Unhook_Invalid_Page_Fault
include vmm.inc

mov     esi, OFFSET32 HookProc     ; points to hook procedure to remove

VMMcall Unhook_Invalid_Page_Fault

The Unhook_Invalid_Page_Fault service removes the specified hook procedure from the invalid-page-fault chain.

Parameter	Description

HookProc	Points to the hook procedure to remove. This procedure must have been previously installed using the Hook_Invalid_Page_Fault service.

Returns

If the carry flag is clear, the hook procedure was removed. Otherwise, the carry flag is set to indicate an error such as the specified procedure was not in the chain.

Uses

Flags

See Also

Hook_Invalid_Page_Fault


Information Services

Get_Cur_VM_Handle	Returns current virtual machine handle

Get_Next_VM_Handle	Returns the next valid virtual machine handle

Get_Sys_VM_Handle	Returns the system virtual machine handle

Get_VMM_Reenter_Count	Returns number of time VMM re-entered

Get_VMM_Version	Returns the VMM version number

GetSet_HMA_Info	Returns or set HMA information

Test_Cur_VM_Handle	Tests for current virtual machine handle

Test_DBCS_Lead_Byte	Tests for legal DBCS lead byte

Test_Debug_Installed	Tests for debugging version

Test_Sys_VM_Handle	Test for system virtual machine handle

Validate_VM_Handle	Validates a virtual machine handle


Get_Cur_VM_Handle
include vmm.inc

VMMcall Get_Cur_VM_Handle

mov     [VM], ebx         ; current VM handle

The Get_Cur_VM_Handle service returns the handle to the currently running virtual machine.

This is an asynchronous service.

This service has no parameters.

Returns

The EBX register contains the handle of the current virtual machine.

Uses

EBX, Flags

See Also

Get_Sys_VM_Handle, Test_Cur_VM_Handle


Get_Next_VM_Handle
include vmm.inc

mov     ebx, VM           ; VM handle

VMMcall Get_Next_VM_Handle

mov     [NextVM], ebx     ; next VM handle

The Get_Next_VM_Handle service returns the handle of the next virtual machine in the virtual machine list maintained by the system. Although each virtual machine appears only once in the list, the order of the handles is not guaranteed. The list is circular, so a virtual device scanning the list should stop scanning when the latest handle returned is equal to the first handle returned.

Parameter	Description

VM	Specifies a handle identifying a virtual machine.

Returns

The EBX register contains the handle of the next virtual machine in the list.

Example

The following example modifies the state of every virtual machine by using the Get_Next_VM_Handle service to retrieve handles of all valid virtual machines:

    VMMcall Get_Cur_VM_Handle

Scan_Loop:

    ; modify the VM state

    VMMcall Get_Next_VM_Handle

    VMMcall Test_Cur_VM_Handle

    jne     Scan_Loop

Uses

EBX, Flags

See Also

Get_Cur_VM_Handle, Test_Cur_VM_Handle


Get_Sys_VM_Handle
include vmm.inc

VMMcall Get_Sys_VM_Handle

mov     [SysVM], ebx            ; system VM handle

The Get_Sys_VM_Handle service returns the handle for the system virtual machine.

This is an asynchronous service.

This service has no parameters.

Returns

The EBX register contains the system virtual machine handle.

Uses

EBX, Flags

See Also

Get_Cur_VM_Handle, Test_Sys_VM_Handle


Get_VMM_Reenter_Count
include vmm.inc

VMMcall Get_VMM_Reenter_Count

jecxz   not_reentered           ; ecx is zero if VMM not re-entered

mov     [Count], ecx            ; otherwise, number of times re-entered

The Get_VMM_Reenter_Count service returns the number of times the VMM has been re-entered as a result of a hardware interrupt, page fault, or other processor exception. Virtual devices typically use this service to determine whether they can call nonre-entrant VMM services.

This service has no parameters.

Returns

The ECX register is zero if the VMM has not been re-entered. Otherwise, the ECX register specifies the number of times the VMM has been re-entered.

Comments

If this service returns a nonzero value, a virtual device may call only VMM services that are asynchronous. If a virtual must call other VMM services, the virtual device can schedule an event using a service such as Schedule_Global_Event. The system calls the event's callback procedure when all VMM services are available.

The Call_Global_Event and Call_VM_Event services call this service to determine whether the event callback procedure should be called immediately.

Uses

Flags

See Also

Call_Global_Event, Call_VM_Event, Schedule_Global_Event, Schedule_VM_Event


Get_VMM_Version
include vmm.inc

VMMcall Get_VMM_Version

mov     [Major], ah         ; major version number

mov     [Minor], al         ; minor version number

mov     [Debug], ecx        ; debug development revision number

The Get_VMM_Version service returns the version number for the Windows virtual machine manager (VMM).

This service has no parameters.

Returns

The carry flag is clear and the AX and ECX registers contain the following version number information:

Register	Description

AH	Specifies the major version number. For Windows 3.1, this number is 3.

AL	Specifies the minor version number. For Windows 3.1, this number is 10.

ECX	Specifies the debug development revision number.

Uses

EAX, Flags


GetSet_HMA_Info
include vmm.inc

mov     ecx, Action         ; zero to get, nonzero to set

mov     dx, A20Enable       ; A20 enable count (if ecx is nonzero)

VMMcall GetSet_HMA_Info

mov     [NoGlobalHMA], eax  ; nonzero if no global HMA user

mov     [XMSCallAddr], ecx  ; loader XMS call address

mov     [A20Enable], edx    ; A20 enable count before Windows started

The GetSet_HMA_Info service returns and sets information related to the high-memory area (HMA) region.

This service lets the XMS driver (in the V86MMGR device) determine whether a global HMA user existed before Windows started and gives the driver access to the HMA enable count.

This service is always valid (not restricted to initialization).

Parameter	Description

Action	Specifies whether to get or set information. If this parameter is zero, the service returns HMA information. Otherwise, it sets the information.

A20Enable	Specifies the A20 enable count to set for the Windows VMM loader. The service uses this parameter only if the Action parameter is nonzero.

Returns

The EAX, ECX, and EX register contain the following HMA information:

Register	Description

EAX	Specifies whether a global HMA user is present. If this register is 0, Windows did not allocate the HMA meaning either there is a global HMA user or there is no HMA. If this register is nonzero, Windows has allocated the HMA, meaning there is no global HMA user.

ECX	Specifies the V86-mode address (segment:offset) that Windows used to call the XMS driver when loading. The segment address is in the high 16 bits of the register.

EDX	Specifies the A20 enable count before Windows started.

Comments

The global HMA flag and loader XMS call address cannot be set.

Uses

EAX, ECX, EDX, Flags


Test_Cur_VM_Handle
include vmm.inc

mov     ebx, VM             ; VM handle to test

VMMcall Test_Cur_VM_Handle

je      is_current          ; zero flag set if current VM handle

The Test_Cur_VM_Handle service tests whether the given virtual machine handle is the handle of the currently running virtual machine.

This is an asynchronous service.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to test.

Returns

The zero flag is set if the handle is for the currently running virtual machine.

Uses

Flags

See Also

Get_Cur_VM_Handle, Test_Sys_VM_Handle


Test_DBCS_Lead_Byte
include vmm.inc

mov     eax, Value          ; value to test

VMMcall Test_DBCS_Lead_Byte

jc      not_valid           ; carry set if value not legal DBCS lead byte

The Test_DBCS_Lead_Byte tests whether the given value is in the legal range for a DBCS lead byte.

Parameter	Description

Value	Specifies the value to test.

Returns

The carry flag is clear if the specified value is in the legal range for DBCS lead bytes. Otherwise, the carry flag is set.

Comments

For non-DBCS versions of Windows, this service always sets the carry flag.

Uses

Flags


Test_Debug_Installed
include vmm.inc

VMMcall Test_Debug_Installed

je      not_installed       ; zero flag set if not installed

The Test_Debug_Installed service tests whether whether the debugging version of the Windows VMM is running.

This service has no parameters.

Returns

The zero flag is set if the debugging version is not installed.

Uses

Flags


Test_Sys_VM_Handle
include vmm.inc

mov     ebx, VM             ; VM handle to test

VMMcall Test_Sys_VM_Handle

je      is_system           ; zero flag set if system VM handle

The Test_Sys_VM_Handle service tests whether the given virtual machine handle is the handle of the system virtual machine.

This is an asynchronous service.

Parameter	Description

VM	Specifies the virtual machine handle to test.

Returns

The zero flag is set if the handle identifies the system virtual machine.

Uses

Flags

See Also

Get_Sys_VM_Handle, Test_Cur_VM_Handle


Validate_VM_Handle
include vmm.inc

mov     ebx, VM             ; VM handle to test

VMMcall Validate_VM_Handle

jc      not_valid           ; carry flag set if VM handle not valid

The Validate_VM_Handle service tests whether the specified virtual machine handle is valid.

This is an asynchronous service.

Parameter	Description

VM	Specifies the virtual machine handle to test.

Returns

The carry flag is set if the handle is not valid.

Uses

Flags

See Also

Test_Cur_VM_Handle, Test_Sys_VM_Handle


Initialization Information Services

Convert_Boolean_String	Converts string to Boolean value

Convert_Decimal_String	Converts a string to a decimal value

Convert_Fixed_Point_String	Converts a string to a fixed-point value

Convert_Hex_String	Converts a string to a hexadecimal value

Get_Config_Directory	Returns the Windows directory

Get_Environment_String	Returns value of an environment variable

Get_Exec_Path	Returns full path of Windows VMM

Get_Machine_Info	Returns machine information

Get_Name_Of_Ugly_TSR	Returns name of uncooperative TSR

Get_Next_Arena	Returns information about the MS-DOS arena

Get_Next_Profile_String	Returns the value of the next profile string

Get_Profile_Boolean	Returns the value of a Boolean entry

Get_Profile_Decimal_Int	Returns the value of a decimal entry

Get_Profile_Fixed_Point	Returns the value of a fixed-point entry

Get_Profile_Hex_Int	Returns the value of a hexadecimal entry

Get_Profile_String	Returns value of a profile string

Get_PSP_Segment	Returns segment address of PSP

GetDOSVectors	Returns original interrupt handler addresses

Locate_Byte_In_ROM	Locates a byte value in system ROM

OpenFile	Opens a file and returns an MS-DOS file handle


Convert_Boolean_String
include vmm.inc

mov     edx, OFFSET32 String        ; points to Boolean string

VMMcall Convert_Boolean_String

jc      not_valid                   ; carry set if string not valid Boolean

mov     [Result], eax               ; 0 if string is false, -1 if true

The Convert_Boolean_String service converts a string representing a Boolean value and returns either -1 or 0 to indicate that the string is true or false.

This service is available during initialization only.

Parameter	Description

String	Points to the null-terminated string representing a Boolean value. The service recognizes at least the following Boolean string values:

String	Meaning

0	False

1	True

False	False

No	False

Off	False

On	True

True	True

Yes	True

Returns

The carry flag is clear if the string represents a valid Boolean value. In this case, the EAX register contains either 0 if the string evaluates to false, or -1 if the string evaluates to true. The carry flag is set if the specified string is not valid.

Uses

Flags, EAX

See Also

Convert_Decimal_String, Convert_Fixed_Point_String, Convert_Hex_String


Convert_Decimal_String
include vmm.inc

mov     edx, OFFSET32 String        ; points to decimal string

VMMcall Convert_Decimal_String

mov     [Value], eax                ; decimal value of string

mov     [TermChar], edx             ; points to terminating character

The Convert_Decimal_String service converts a string representing a decimal number into a value. The service also returns a pointer to the character in the string that marked the end of the decimal number.

This service is only valid during initialization.

Parameter	Description

String	Points to the null-terminated string to convert. The string can be any combination of decimal digits and may preceded by a plus sign (+) or minus sign (-) to indicate a positive or negative value.

Returns

The EAX register contains the value of decimal string, and the EDX register contains the address of the character in the string that terminated the decimal value.

Comments

If the string is empty or does not contain a valid decimal integer, Convert_Decimal_String returns zero, and the EDX register continues to point to the first character in the string.

Uses

EAX, EDX, Flags

See Also

Convert_Boolean_String, Convert_Fixed_Point_String, Convert_Hex_String


Convert_Fixed_Point_String
include vmm.inc

mov     ecx, Places     ; number of decimal places

mov     edx, String     ; points to string to convert

VMMcall Convert_Fixed_Point_String

mov     [Value], eax    ; fixed-point value

mov     [TermChar], edx ; pointer to terminating character

The Convert_Fixed_Point_String service converts a string representing a fixed-point number into a fixed-point value. This service also returns a pointer to the character in the string that marked the end of the number.

This service is only valid during initialization.

Parameter	Description

Places	Specifies the number of digits after the decimal point to convert. If a fixed-point number has extra digits, the service skips over the digits without calculating them into the fixed-point value.

String	Points to the null-terminated string to convert. The Comments section describes the format of the string.

Returns

The EAX register contains the normalized value of fixed-point number; the actual value is computed as EAX * 10 ** (-Places). The EDX register contains the address of the character in the string marking the end of the fixed-point number.

Comments

A fixed-point number is a decimal number that consists of an integer, a fraction, or a combination of integer and fraction. The integer can be any combination of decimal digits and may be preceded by a plus sign (+) or a minus sign (-) to indicate a positive or negative fixed-point value. The fraction can be any combination of decimal digits but must be preceded with a decimal point (.).

Uses

EAX, EDX, Flags

See Also

Convert_Boolean_String, Convert_Decimal_String, Convert_Hex_String


Convert_Hex_String
include vmm.inc

mov     edx, OFFSET32 String        ; points to hexadecimal string

VMMcall Convert_Hex_String

mov     [Value], eax                ; value of string

mov     [TermChar], edx             ; points to terminating character

The Convert_Hex_String service converts a string representing a hexadecimal number into a value. The service also returns a pointer to the character in the string that marked the end of the hexadecimal number.

This service is only valid during initialization.

Parameter	Description

String	Points to the null-terminated string to convert. The string can be any combination of hexadecimal digits (0-9, A-F), and may terminated with an uppercase or lowercase letter H.

Returns

The EAX register contains the value of the hexadecimal string and the EDX register contains the address of the character in the string that terminated the hexadecimal value. If a letter H terminates the number, EDX contains the address the character immediately following the H.

Uses

Flags

See Also

Convert_Boolean_String, Convert_Decimal_String, Convert_Fixed_Point_String


Get_Config_Directory
include vmm.inc

VMMcall Get_Config_Directory

mov     [WinDir], edx       ; points to the Windows directory

The Get_Config_Directory service returns a pointer to a null-terminated string that specifies the fully qualified path of the directory containing the Windows configuration files. Virtual devices use this service to locate files such as SYSTEM.INI.

This service is available during initialization only.

This service has no parameters.

Returns

The EDX register points to the null-terminated string specifying the configuration directory. If the WINDIR environment variable is defined when Windows starts, EDX points to the value associated with WINDIR regardless of whether it specifies the actual directory where SYSTEM.INI is found.

Comments

The string returned by this service always ends with a backslash (\).

Uses

EDX, Flags


Get_Environment_String
include vmm.inc

mov     esi, OFFSET32 Variable  ; points to name of environment variable

VMMcall Get_Environment_String

jc      not_found               ; carry set if variable not found

mov     [Value], edx            ; points to value of environment variable

The Get_Environment_String service returns the value of the specified environment variable.

This service is only available during initialization.

Parameter	Description

Variable	Points to a null-terminated string specifying the name of an MS-DOS environment variable. This service is not sensitive to case, so the name may be given in any combination of uppercase and lowercase letters.

Returns

The carry flag is clear and the EDX register points to a null-terminated string specifying the value of the environment variable if the service is successful. Otherwise, the carry flag is set to indicate that the environment variable could not be found.

Comments

Environment variables, set using the MS-DOS set command, are a limited resource. Although some virtual devices use environment variables as a way to set operating parameters, this is not recommended unless the variable is used by a set of programs, MS-DOS device drivers, and virtual devices.

Uses

EDX, Flags


Get_Exec_Path
include vmm.inc

VMMcall Get_Exec_Path

mov     [Path], edx     ; points to full path of WIN386.EXE

mov     [Length], ecx   ; number of characters up to and including last \\

The Get_Exec_Path service returns a null-terminated string that specifies the full path of the Windows virtual machine manager (WIN386.EXE). Virtual devices often use this service to locate executable files that are not in directories specified by the PATH environment variable.

This service is only available during initialization.

This service has no parameters.

Returns

The EDX register points to a null-terminated string specifying the full path of the VMM. The ECX register contains a count of characters up to and including the last backslash (\).

Uses

ECX, EDX


Get_Machine_Info
include vmm.inc

VMMcall Get_Machine_Info

mov     [Major], AH         ; MS-DOS major version number

mov     [Minor], AL         ; MS-DOS minor version number

mov     [OEM], BH           ; MS-DOS OEM serial number

mov     [Model], BL         ; machine model byte

mov     [Type], EBX         ; machine type flags (high-order 16-bits)

mov     [SysConf], ECX      ; points to System Configuration Parameters

mov     [Equip], EDX        ; equipment flags

The Get_Machine_Info service returns information about the computer system that Windows is running on.

This service has no parameters.

Returns

The AX, EBX, ECX, and EDX registers contain the following information:

Register	Description

AH	MS-DOS major version number

AL	MS-DOS minor version number

BH	MS-DOS OEM serial number

BL	Machine model byte (from address F000:FFFE in system ROM)

EBX	Machine type flags (in the high-order 16-bits) as follows:

Value	Meaning

GMIF_80486	80486 processor

GMIF_PCXT	PCXT accelerator

GMIF_MCA	Micro Channel

GMIF_EISA	EISA

ECX	Ring 0 linear address to System Configuration Parameters (as returned from BIOS service Interrupt 15h, AH=C0h) Applies only to PS/2 or computers with extended BIOS. See the PS/2 BIOS documentation for details.

EDX	Equipment flags (as returned from Interrupt 11h)

Comments

The address returned in the ECX register points to a copy of the system configuration parameters because the actual parameters may have been moved into a buffer which is subject to page remapping.

Uses

EAX, EBX, ECX, EDX, Flags


Get_Name_Of_Ugly_TSR
include vmm.inc

VMMcall Get_Name_Of_Ugly_TSR

jz      no_ugly_TSR         ; zero set if no ugly TSRs present

mov     [Name], eax         ; first 4 characters of TSR name

mov     [Name+4], ebx       ; last 4 characters of TSR name

The Get_Name_Of_Ugly_TSR service returns the name of an uncooperative TSR. During its real-mode initialization, the virtual MS-DOS manager checks for and records the names of any TSRs that may prevent other MS-DOS programs from running. Get_Name_Of_Ugly_TSR checks the list and returns one of the TSR names (if any) so that virtual devices can determine whether they can successfully operate. Although more than one ugly TSR may be present in the list, the service chooses only one name to return.

This service is only available during initialization and only available for Windows 3.1 and later.

This service has no parameters.

Returns

The zero flag is set and the EAX and EBX registers are set to zero if no ugly TSRs are present. Otherwise, the zero flag is clear and the EAX register contains the first four characters of the TSR name, and the EBX register contains the last four characters.

Uses

EAX, EBX, Flags


Get_Next_Arena
include vmm.inc

mov     ecx, 0              ; must be zero

VMMcall Get_Next_Arena

mov     [Data], eax         ; data value

mov     [Flags], ecx        ; high MS-DOS memory flags

mov     [Memory], edx       ; points to array of Common_Memory_struc

The Get_Next_Arena service returns a pointer to an MS-DOS data structure.

Virtual devices must not use this service; it is intended for exclusive use by the virtual MS-DOS manager.

This service has no parameters.

Returns

The EAX, ECX, and EDX registers contain the following information:

Register	Description

EAX	Specifies a data value.

ECX	Specifies the high MS-DOS flags. It can be a combination of the following values:

Value	Meaning

GNA_HiDOSLinked	Set if high MS-DOS arenas were linked in when Windows was started.

GNA_IsHighDOS	Set if high MS-DOS arenas exist.

EDX	Points to an array of Common_Memory_struc structures specifying the addresses and sizes of high MS-DOS memory segments. Each element of the list has the following form:

    Common_Memory_struc struc

      CM_seg    dw  ?   ; segment address of start

      CM_size   dw  ?   ; size in paragraphs

    Common_Memory_struc ends

The last element of array contains zero.

Uses

EAX, ECX, EDX, and Flags


Get_Next_Profile_String
include vmm.inc

mov     edx, Profile    ; points to the previous entry value

mov     edi, Keyname    ; points to the entry name

VMMcall Get_Next_Profile_String

jc      no_next         ; carry set if there is no next value

mov     [Next], edx     ; points to entry value of next profile string

The Get_Next_Profile_String service searches the SYSTEM.INI file for the first entry that follows the entry specified by the Profile parameter, and that has the given keyname. This service returns a pointer to this next entry if it is found.

Virtual devices typically use this service if they have more than one entry having the same keyname. A virtual device retrieves the first string using the Get_Profile_String service, then uses Get_Next_Profile_String to retrieve all subsequent entries. In all cases, the virtual device must not modify the returned string.

Parameter	Description

Profile	Points to a null-terminated string specifying the value of the previous entry. The string must have been previously returned using the Get_Profile_String or Get_Next_Profile_String service.

Keyname	Points to a null-terminated string identifying the keyname for the entry.

Returns

If the carry flag is clear, the EDX register contains the address of the next string having the specified keyname. The carry flag is set if there are no more matching entries.

Uses

EDX, Flags

See Also

Get_Profile_String


Get_Profile_Boolean
include vmm.inc

mov     eax, Default            ; default value

mov     esi, OFFSET32 Profile   ; points to section name

mov     edi, OFFSET32 Keyname   ; points to entry name

VMMcall Get_Profile_Boolean

jc      not_found           ; carry set if entry not found

jz      no_value            ; zero set if entry has no value

mov     [Value], eax        ; entry value is either 0 (false) or -1 (true)

The Get_Profile_Boolean service returns the value of an Boolean entry in the SYSTEM.INI file. The Profile and Keyname parameters specify the section and entry to search for.

This service is only available during initialization.

Parameter	Description

Default	Specifies the default value to return if the entry is not found, or has no current value.

Profile	Specifies a null-terminated string identifying the section in the SYSTEM.INI file to search. If Profile is zero, the service searches the [386Enh] section.

Keyname	Points to a null-terminated string identifying the name of the entry to search for.

Returns

If the carry and zero flags are clear, the specified entry is found and is a valid Boolean string. In this case, the EAX register is set to -1 or 0 indicating that the entry value evaluates to true or false, respectively.

If the carry flag is clear and the zero flag is set, the specified entry exists but has no corresponding value. If the carry flag is set, the entry cannot be found or the entry does not represent a Boolean value. In these cases, the EAX register is set to the Default value.

Comments

This service returns the Default value unless the value corresponding to the specified entry is a valid Boolean string. A Boolean string can be one of the following:

String	Meaning

0	False

1	True

False	False

N	False

No	False

Off	False

On	True

True	True

Y	True

Yes	True

Non-English versions of Windows may have language-specific additions to this list.

Uses

Flags

See Also

Get_Profile_Decimal_Int, Get_Profile_Fixed_Point, Get_Profile_Hex_Int


Get_Profile_Decimal_Int
include vmm.inc

mov     eax, Default            ; default value

mov     esi, OFFSET32 Profile   ; points to section name

mov     edi, OFFSET32 Keyname   ; points to entry name

VMMcall Get_Profile_Decimal_Int

jc      not_found               ; carry set if entry not found

jz      no_value                ; zero set if entry has no value

mov     [Value], eax            ; entry value

The Get_Profile_Decimal_Int service returns the value of a decimal-number entry in the SYSTEM.INI file. The Profile and Keyname parameters specify the section and entry to search for.

This service is only available during initialization.

Parameter	Description

Default	Specifies the default value to return if the entry is not found or has no current value.

Profile	Specifies a null-terminated string identifying the section in the SYSTEM.INI file to search. If Profile is zero, the service searches the [386Enh] section.

Keyname	Points to a null-terminated string identifying the name of the entry to search for.

Returns

If the carry and zero flags are clear, the specified entry is found and is a valid decimal number. In this case, the EAX register is set to the value of the number.

If the carry flag is clear and the zero flag is set, the specified entry exists but has no corresponding value. If the carry flag is set, the entry cannot be found or the entry does not represent a valid decimal number. In these cases, the EAX register is set to the Default value.

Comments

A valid decimal number consists of one or more decimal digits and contains no embedded spaces or decimal points. The decimal number can be preceded with a plus sign (+) or minus sign (-) to indicate a positive or negative number, respectively.

Uses

Flags

See Also

Get_Profile_Boolean, Get_Profile_Fixed_Point, Get_Profile_Hex_Int


Get_Profile_Fixed_Point
include vmm.inc

mov     eax, Default            ; default value

mov     ecx, Places             ; number of digits after decimal point

mov     esi, OFFSET32 Profile   ; points to section name

mov     edi, OFFSET32 Keyname   ; points to entry name

VMMcall Get_Profile_Fixed_Point

jc      not_found               ; carry set if entry not found

jz      no_value                ; zero set if entry has no value

mov     [Value], eax            ; entry value

The Get_Profile_Fixed_Point service returns the value of a fixed-point-number entry in the SYSTEM.INI file. The Profile and Keyname parameters specify the section and entry to search for.

This service is only available during initialization.

Parameter	Description

Default	Specifies the default value to return if the entry is not found or has no current value.

Places	Specifies the number of digits after the decimal point to convert. If fixed-point number has extra digits, the service ignores them.

Profile	Specifies a null-terminated string identifying the section in the SYSTEM.INI file to search. If Profile is zero, the service searches the [386Enh] section.

Keyname	Points to a null-terminated string identifying the name of the entry to search for.

Returns

If the carry and zero flags are clear, the specified entry is found and is a valid fixed-point number. In this case, the EAX register is set to the normalized value of the number; the actual value is computed as EAX * 10 ** (-Places).

If the carry flag is clear and the zero flag is set, the specified entry exists but has no corresponding value. If the carry flag is set, the entry cannot be found or the entry does not represent a valid fixed-point number. In these cases, the EAX register is set to the Default value.

Comments

A valid fixed-point number is a decimal number that consists of an integer, a fraction, or a combination of integer and fraction. The integer can be any combination of decimal digits, and may be preceded by a plus sign (+) or a minus sign (-) to indicate a positive or negative fixed-point value. The fraction can be any combination of decimal digits but must be preceded with a decimal point (.).

Uses

Flags

See Also

Get_Profile_Boolean, Get_Profile_Decimal_Int, Get_Profile_Hex_Int


Get_Profile_Hex_Int
include vmm.inc

mov     eax, Default            ; default value

mov     esi, OFFSET32 Profile   ; points to section name

mov     edi, OFFSET32 Keyname   ; points to entry name

VMMcall Get_Profile_Hex_Int

jc      not_found               ; carry set if entry not found

jz      no_value                ; zero set if entry has no value

mov     [Value], eax            ; entry value

The Get_Profile_Hex_Int service returns the value of a hexadecimal-number entry in the SYSTEM.INI file. The Profile and Keyname parameters specify the section and entry to search for.

This service is only available during initialization.

Parameter	Description

Default	Specifies the default value to return if the entry is not found or has no current value.

Profile	Specifies a null-terminated string identifying the section in the SYSTEM.INI file to search. If Profile is zero, the service searches the [386Enh] section.

Keyname	Points to a null-terminated string identifying the name of the entry to search for.

Returns

If the carry and zero flags are clear, the specified entry is found and is a valid hexadecimal number. In this case, the EAX register is set to the value of the number.

If the carry flag is clear and the zero flag is set, the specified entry exists but has no corresponding value. If the carry flag is set, the entry cannot be found or the entry does not represent a valid hexadecimal number. In these cases, the EAX register is set to the Default value.

Comments

A valid hexadecimal number consist of any combination of hexadecimal digits (0-9, A-F), and can be terminated with the uppercase or lowercase letter H.

Uses

Flags

See Also

Get_Profile_Decimal_Int, Get_Profile_Fixed_Point, Get_Profile_Hex_Int


Get_Profile_String
include vmm.inc

mov     edx, OFFSET32 Default ; points to default string (optional)

mov     esi, OFFSET32 Profile ; points to section name

mov     edi, OFFSET32 Keyname ; points to entry name

VMMcall Get_Profile_String

jc      not_found               ; carry set if entry not found

mov     [Value], edx            ; points to entry value string

The Get_Profile_String service searches the SYSTEM.INI file for a specified entry and returns a pointer to a null-terminated string representing the entry value.

This service is only available during initialization.

Parameter	Description

Default	Points to a null-terminated string to be returned if the entry is not found or has no current value.

Profile	Specifies a null-terminated string identifying the section in the SYSTEM.INI file to search. If Profile is zero, the service searches the [386Enh] section.

Keyname	Points to a null-terminated string identifying the name of the entry to search for.

Returns

If the carry flag is clear, the EDX register contains the address of the null-terminated string representing the entry value. If the carry flag is set, the string cannot be found.

Comments

A virtual device must not modify the string pointed to by the EDX register. If modification is required, the virtual device must copy the string and modify the copy.

Uses

EDX, Flags

See Also

Get_Next_Profile_String


Get_PSP_Segment
include vmm.inc

VMMcall Get_PSP_Segment

mov     [PSP], eax          ; segment address of PSP

The Get_PSP_Segment service returns the segment address of program segment prefix (PSP) for the Windows virtual machine manager (WIN386.EXE). Virtual devices typically use this service to retrieve values from the PSP that can not be retrieve using the Get_Exec_Path and Get_Environment_String services.

This service is only available during initialization.

This service has no parameters.

Returns

The EAX register contains the segment address for the program segment prefix. The high word is always zero.

Comments

This service returns a segment address. To convert the segment address to an physical address, shift it left by 4 bits.

Uses

EAX, Flags

See Also

Get_Environment_String, Get_Exec_Path


GetDOSVectors
include vmm.inc

VMMcall GetDOSVectors

mov     [Int23], eax            ; V86 address of original Int23 handler

mov     [Int24], edx            ; V86 address of original Int24 handler

The GetDOSVectors service returns the Interrupt 23h and Interrupt 24h vectors as originally set by MS-DOS for the Windows virtual machine manager. When Windows starts, the VMM changes the original Interrupt 23h and 24h vectors to the addresses of its own handlers. When a virtual machine starts, the virtual MS-DOS manager resets these vectors to the original handlers using this service to retrieve the original addresses.

Virtual devices must not use this service; this service is reserved for exclusive use by the virtual MS-DOS manager.

This service has no parameters.

Returns

The EAX register contains the V86-mode address (segment:offset) for the MS-DOS Interrupt 23h handler, and the EDX register contains the V86-mode address (segment:offset) for the MS-DOS Interrupt 24h handler.

Uses

EAX, EDX

See Also

Get_PSP_Segment


Locate_Byte_In_ROM
include vmm.inc

mov     al, Byte            ; byte to locate

VMMcall Locate_Byte_In_ROM

jc      not_found           ; carry set if byte not found

mov     [Location], eax     ; linear address of byte

The Locate_Byte_In_ROM service scans the system ROM for a specified byte. Virtual devices use this service to locate single byte instructions, such as the iret instruction, that must be protected from modification by programs running in a virtual machine.

Parameter	Description

Byte	Specifies the value of the byte to search for.

Returns

If the carry flag is clear, the EAX register contains the linear address of the byte. This address will be less than 1 megabyte. If the carry flag is set, the byte was not found or the user has disabled the service.

Comments

Users can disable this service by setting to false the SystemROMBreakpoint setting in the [386Enh] section of the SYSTEM.INI file.

Uses

EAX, Flags


OpenFile
include vmm.inc

mov     edx, OFFSET32 Filename  ; points to name of file to open

mov     edi, OFFSET32 Buffer    ; points to buffer to receive full path

VMMcall OpenFile

jc      not_found               ; carry flag is set if file not found

mov     [Handle], eax           ; MS-DOS file handle

The OpenFile service opens the file having the specified name. If the Filename parameter specifies only a filename (no drive letter or path separators included), this service searches for the file in the directories specified by the following:

WINDIR environment variable

First command-line argument (argv[0]) of Windows

Current working directory

PATH environment variable

Otherwise, the service does not search for the file. In either case, the service attempts to opens the file for reading (in compatibility mode), and returns the MS-DOS file handle if it is successful.

This service is only available during initialization.

Parameter	Description

Filename	Points to a null-terminated string specifying the name of the file to open.

Buffer	Points to a buffer that receives the full path of the file (if found). The buffer must be at least 128 bytes.

Returns

If the carry flag is clear, the EAX register contains a valid MS-DOS file handle (in the low word). The handle can be used in subsequent MS-DOS functions to read from or close the file. If the carry flag is set, the file cannot be found.

Comments

If WINDIR and PATH environment variables are not well formed, this service cannot guarantee that the full path copied to the Buffer parameter will be well formed.

This service fails if the current virtual machine cannot support a call to the Exec_Int service, or if the virtual machine has already used the _Allocate_Temp_V86_Data_Area service to allocate the temporary buffer.

Uses

EAX, Flags

See Also

_Allocate_Temp_V86_Data_Area, Exec_Int


I/O Trapping Services

Disable_Global_Trapping	Disables global I/O trapping

Disable_Local_Trapping	Disables local I/O trapping

Enable_Global_Trapping	Enables global I/O trapping

Enable_Local_Trapping	Enables local I/O trapping

Install_IO_Handler	Install an I/O callback procedure

Install_Mult_IO_Handlers	Install I/O handlers for multiple ports

Simulate_IO	Simulates input and output


Disable_Global_Trapping
include vmm.inc

mov     edx, Port           ; I/O port number

VMMcall Disable_Global_Trapping

The Disable_Global_Trapping service disables I/O port trapping for the specified I/O port. This applies to every virtual machine.

This service must not be used unless an I/O callback procedure has been installed for the given port using the Install_IO_Handler or Install_Mult_IO_Handlers service during initialization.

Parameter	Description

Port	Specifies the number of the I/O port for which global trapping is to be disabled.

Returns

This service has no return value.

Comments

The system applies to current global trapping state to each new virtual machine as it is created. When the system first starts, global trapping is enabled by default.

Uses

Flags

See Also

Enable_Global_Trapping, Install_IO_Handler, Install_Mult_IO_Handlers


Disable_Local_Trapping
include vmm.inc

mov     ebx, VM         ; VM handle

mov     edx, Port       ; I/O port number

VMMcall Disable_Local_Trapping

The Disable_Local_Trapping service disables I/O port trapping for the specified I/O port. This applies only to the specified virtual machine.

This service must not be used unless an I/O callback procedure has been installed for the given port using the Install_IO_Handler or Install_Mult_IO_Handlers service during initialization.

Parameter	Description

VM	Specifies a handle identifying the virtual machine for which to disable I/O trapping.

Port	Specifies the number of the I/O port for which trapping is disabled.

Returns

This service has no return value.

Uses

Flags

See Also

Enable_Local_Trapping, Install_IO_Handler, Install_Mult_IO_Handlers


Enable_Global_Trapping
include vmm.inc

mov     edx, Port           ; I/O port number

VMMcall Enable_Global_Trapping

The Enable_Global_Trapping service enables I/O port trapping for the specified port. This applies to every virtual machine.

This service must not be used unless an I/O callback procedure has been installed for the given port using the Install_IO_Handler or Install_Mult_IO_Handlers service during initialization.

Parameter	Description

Port	Specifies the number of the I/O port for which global trapping is to be enabled.

Returns

This service has no return value.

Comments

The system applies to current global trapping state to each new virtual machine as it is created. When the system first starts, global trapping is enabled by default.

Uses

Flags

See Also

Disable_Global_Trapping, Install_IO_Handler, Install_Mult_IO_Handlers


Enable_Local_Trapping
include vmm.inc

mov     ebx, VM         ; VM handle

mov     edx, Port       ; I/O port number

VMMcall Enable_Local_Trapping

The Enable_Local_Trapping service enables I/O port trapping for the specified port. This applies to the specified virtual machine only.

This service must not be used unless an I/O callback procedure has been installed for the given port using the Install_IO_Handler or Install_Mult_IO_Handlers service during initialization.

Parameter	Description

VM	Specifies a handle identifying the virtual machine for which to enable I/O trapping.

Port	Specifies the number of the I/O port for which trapping is enabled.

Returns

This service has no return value.

Uses

Flags

See Also

Disable_Local_Trapping, Install_IO_Handler, Install_Mult_IO_Handlers


Install_IO_Handler
include vmm.inc

mov     esi, IOCallback     ; points to callback procedure

mov     edx, Port           ; I/O port number

VMMcall Install_IO_Handler

jc      not_installed       ; carry set if procedure not installed

The Install_IO_Handler service installs a callback procedure for I/O port trapping and enables trapping for the specified port. Only one procedure may be installed for a given port.

This service is only available during initialization.

Parameter	Description

IOCallback	Points to the callback procedure. See the Comments for more information about the callback procedure.

Port	Specifies the I/O port to be trapped.

Returns

The carry flag is clear if the service successfully installs the callback procedure. If the carry flag is set, a callback procedure is already installed for the specified port or the system limit for I/O callback procedures has been reached.

Comments

The system calls the callback procedure whenever a program in a virtual machine attempts to access the specified I/O port, and I/O trapping is enabled. The system calls the procedure as follows:

mov     ebx, VM             ; current VM handle

mov     ecx, IOType         ; type of I/O

mov     edx, Port           ; port number

mov     ebp, OFFSET32 crs   ; points to a Client_Reg_Struc

mov     eax, Data           ; output data (if I/O type is output)

call    [IOCallback]

mov     [Data], eax         ; input data (if I/O type is input)

The VM parameter specifies the current virtual machine, Port specifies the I/O port, and crs points to a Client_Reg_Struc structure containing the register contents for the current virtual machine.

The IOType parameter specifies the type of input or output operation requested and determines whether the callback procedure receives data in the EAX register or must return data in the EAX register. The IOType parameter can be a combination of the following values:

Value	Meaning

Byte_Input	Input a single byte; place in AL if String_IO not given.

Byte_Output	Output a single byte from AL if String_IO not given.

Word_Input	Input a word; place in AX if String_IO not given.

Word_Output	Output a word from AX if String_IO not given.

Dword_Input	Input a double word; place in EAX if String_IO not given.

Dword_Output	Output a double word from EAX if String_IO not given.

String_IO	Input or output a string. The high 16-bits specifies segment address of buffer containing the string to output or to receive the string input.

Rep_IO	Repeat the input or output string operation the number of times specified by the Client_CX field in the Client_Reg_Struc structure.

Addr_32_IO	Use 32-bit address offsets for input or output string operations. If this value is not given, the 16-bit offsets are used.

Reverse_IO	Decrement string address on each input or output operation. If this value is not given, the string address is incremented on each operation.

A virtual machine can disable trapping of a port for every or for specific virtual machines by using the Disable_Global_Trapping and Disable_Local_Trapping services.

Uses

Flags

See Also

Disable_Global_Trapping, Disable_Local_Trapping, Install_Mult_IO_Handlers


Install_Mult_IO_Handlers
include vmm.inc

mov     edi, OFFSET32 IOTable   ; points to an I/O table

VMMcall Install_Mult_IO_Handlers

jnc     installed               ; carry clear if all procedures installed

mov     [BadPort], edx          ; I/O port number that failed

The Install_Mult_IO_Handlers service installs I/O callback procedures for one or more I/O ports.

This service is only available during initialization.

Parameter	Description

IOTable	Points to an I/O table created using the Begin_Vxd_IO_Table, End_Vxd_IO_Table, and Vxd_IO macros. See the Comments section for more information about the table.

Returns

The carry flag is clear if all callback procedures are installed for the specified ports. If the carry flag is set, the EDX register contains the number of the I/O port for which the procedure could not be installed.

Comments

This service repeatedly calls the Install_IO_Handler service until all entries in the specified I/O table have been installed.

A virtual device can create an I/O table using the Begin_Vxd_IO_Table, End_Vxd_IO_Table, and Vxd_IO macros. The following example shows a table containing three entries for ports 30, 31, and 32:

Begin_Vxd_IO_Table  My_IO_Table

Vxd_IO              30,IO_Handler_1

Vxd_IO              31,IO_Handler_2

Vxd_IO              32,IO_Handler_1

End_Vxd_IO_Table    My_IO_Table

Uses

Flags

See Also

Begin_Vxd_IO_Table, End_Vxd_IO_Table, Install_IO_Handler, Vxd_IO


Simulate_IO
include vmm.inc

mov     eax, Data           ; data for output operations

mov     ebx, VM             ; current VM handle

mov     ecx, IOType         ; type of I/O (as passed to I/O trap routine)

mov     edx, Port           ; I/O port number

mov     ebp, OFFSET32 crs   ; points to a Client_Reg_Struc

VMMjmp  Simulate_IO

mov     [Data], eax         ; data for input operation

The Simulate_IO service reduces complex I/O instructions to simpler I/O operations. An I/O callback procedure typically jumps to this service whenever the procedure receives a type of I/O that it does not directly support.

Parameter	Description

Data	Specifies the data for an output operation. This parameter is used only if the IOType parameter specifies an output operation.

VM	Specifies a handle identifying the current virtual machine.

IOType	Specifies the type of I/O operation. This parameter can be a combination of the following values:

Value	Meaning

Byte_Input	Input a single byte; place in AL if String_IO not given.

Byte_Output	Output a single byte from AL if String_IO not given.

Word_Input	Input a word; place in AX if String_IO not given.

Word_Output	Output a word from AX if String_IO not given.

Dword_Input	Input a double word; place in EAX if String_IO not given.

Dword_Output	Output a double word from EAX if String_IO not given.

String_IO	Input or output a string. The high 16-bits specifies segment address of buffer containing the string to output or to receive the string input.

Rep_IO	Repeat the input or output string operation the number of times specified by the Client_CX field in the Client_Reg_Struc structure.

Addr_32_IO	Use 32-bit address offsets for input or output string operations. If this value is not given, the 16-bit offsets are used.

Reverse_IO	Decrement string address on each input or output operation. If this value is not given, the string address is incremented on each operation.

Port	Specifies the number of the I/O port through which to carry out the operation.

crs	Points to a Client_Reg_Struc structure containing the register contents for the current virtual machine.

Returns

The EAX register contains input data if the IOType parameter specifies an input operation. IOType also specifies the size of the data in EAX.

Comments

The parameters to this service are identical to the parameters passed to an I/O callback procedure. A callback procedure should jump to this service using the VMMjmp macro with all of the registers in the same state as when the procedure was called. The procedure may modify the ESI and EDI register before jumping, if necessary.

Uses

EAX, EBX, ECX, EDX, ESI, EDI, Flags

See Also

Dispatch_Byte_IO, Emulate_Non_Byte_IO


Linked List Services

List_Allocate	Allocates a new node for a list

List_Attach	Attaches a node to the head of the list

List_Attach_Tail	Attaches a node to the end of the list

List_Create	Creates a list

List_Deallocate	Deallocates a node

List_Destroy	Destroys a list

List_Get_First	Returns the address of the first node

List_Get_Next	Returns address of next node in the list

List_Insert	Inserts a node into a list

List_Remove	Removes a node from the list

List_Remove_First	Removes first node in list


List_Allocate
include vmm.inc

mov     esi, List       ; list handle

VMMcall List_Allocate

jc      not_allocated   ; carry set if error

mov     [Node], eax     ; address of new node

The List_Allocate service allocates a new node for the specified list. A virtual device can attach the new node to the list using the List_Attach or List_Insert service. The contents of the new node are undefined.

Parameter	Description

List	Specifies the handle for the list.

Returns

The EAX register contains the address of the new node if this service is successful. For lists created using the LF_Alloc_Error value, the carry flag is clear if the service is successful. For other lists, this service never returns if the new node cannot be allocated.

Comments

This service normally allocates nodes from a pool of free nodes. This prevents the overhead of calling the _HeapAlloc service for every node allocation. If the list is created using the LF_Use_Heap value, this service calls the _HeapAlloc service for each node.

Uses

EAX, Flags

See Also

List_Attach, List_Create, List_Deallocate, List_Insert


List_Attach
include vmm.inc

mov     esi, List       ; list handle

mov     eax, Node       ; address of node to attach

VMMcall List_Attach

The List_Attach service attaches a list node to the head (front) of a list. A virtual device can attach a node to any list that has a matching node size. This service can be used, for example, to move a node from one list to another.

Parameter	Description

List	Specifies the handle identifying a list. The handle must have been previously created using the List_Create service.

Node	Specifies the address of the node to attach. The node must have been previously created using the List_Allocate service.

Returns

This service has no return value.

Comments

The service attaches the node to the head of the list. Subsequent calls to the List_Get_First service return the address of this node. The address of the previous head of the list can be retrieved using the List_Get_Next service.

Uses

Flags

See Also

List_Allocate, List_Create, List_Get_First, List_Get_Next, List_Remove, List_Remove_First


List_Attach_Tail
include vmm.inc

mov     esi, List       ; list handle

mov     eax, Node       ; address of node to attach

VMMcall List_Attach_Tail

The List_Attach_Tail service attaches a list node to the tail (end) of a list. A virtual device can attach a node to any list that has a matching node size. This service can be used, for example, to move a node from one list to another.

Parameter	Description

List	Specifies the handle identifying a list. The handle must have been previously created using the List_Create service.

Node	Specifies the address of the node to attach. The node must have been previously created using the List_Allocate service.

Returns

This service has no return value.

Comments

The service attaches the node to the end of the list. A virtual device can retrieve the address of the node by calling the List_Get_Next service and specifying the address of the previous end of the list.

Uses

Flags

See Also

List_Allocate, List_Create, List_Get_Next, List_Remove


List_Create
include vmm.inc

mov     eax, Flags      ; creation flags

mov     ecx, NodeSize   ; size in bytes of each node in list

VMMcall List_Create

jc      error           ; carry set if error

mov     [List], eax     ; list handle

The List_Create service creates a new list structure and returns a list handle that virtual devices use in subsequent calls to other list services.

Parameter	Description

Flags	Specifies the creation flags. This parameter can be a combination of the following values:

Value	Meaning

LF_Use_Heap	Allocates nodes on the system heap. This value must not be used in combination with the LF_Async value.

LF_Async	Creates an asynchronous list that can be used while processing interrupts.

LF_Alloc_Error	Directs the List_Allocate service to returns with carry flag set if new node could not be allocated.

NodeSize	Specifies the size in bytes of each node in the list.

Returns

If carry flag is clear, the ESI register contains the list handle. The carry flag is set to indicate an error.

Comments

If a virtual device requires large nodes, it should specify the LF_Use_Heap value to force the nodes to be allocated from the system heap. All allocate and deallocate calls for lists created in this way use the _HeapAlloc and _HeapFree services to create and destroy nodes.

To access a list during hardware interrupts, a virtual device must set the LF_Async value when creating the list. This forces list operations to be atomic operations which cannot be re-entered. When using an asynchronous list, the virtual device must disable interrupts before calling the list services. The virtual device must disable interrupts even if when not calling during an interrupt. The virtual device must use the pushf, cli, and popf instructions to disable and re-enable interrupts. It must not use the sti instruction to enable interrupts unless other documentation states that this is premitted.

If the LF_Alloc_Error value is not specified, the system crashes the current virtual machine if the List_Allocate service fails. If this value is specified, List_Allocate returns with the carry flag set when an allocation fails.

Uses

ESI, Flags

See Also

List_Allocate, List_Deallocate, List_Destroy


List_Deallocate
include vmm.inc

mov     esi, List       ; list handle

mov     eax, Node       ; address of node to deallocate

VMMcall List_Deallocate

The List_Deallocate service deallocates the specified node. Once a virtual device deallocates a node, it must not attempt to use the node.

Parameter	Description

List	Specifies the handle identifying a list. The handle must have been previously created using the List_Create service.

Node	Specifies the address of the node to attach. The node must have been previously created using the List_Allocate service.

Returns

This service has no return value.

Comments

This service normally never destroys a node. Instead, the service places the node back in the free pool. The node can then quickly be reclaimed when the List_Allocate service is called. If the list is created using the LF_Use_Heap value, this service calls the _HeapFree service for each node.

Uses

EAX, Flags

See Also

_HeapFree, List_Allocate, List_Create


List_Destroy
include vmm.inc

mov     esi, List       ; list handle

VMMcall List_Destroy

The List_Destroy service deallocates all nodes in a list and destroys the list handle. Once a virtual device destroys a list, it must not attempt to use the list handle.

Parameter	Description

List	Specifies the handle identifying a list. The handle must have been previously created using the List_Create service.

Returns

This service has no return value.

Uses

ESI, Flags

See Also

List_Create


List_Get_First
include vmm.inc

mov     esi, List       ; list handle

VMMcall List_Get_First

jz      empty_list      ; zero flag set if list is empty

mov     [Node], eax     ; address of first node

The List_Get_First service returns a pointer to the first node in a list. If the list is empty, it return 0 and the zero flag is set.

Parameter	Description

List	Specifies the handle identifying a list. The handle must have been previously created using the List_Create service.

Returns

If the zero flag is clear, the EAX register contains the address of the first node in the list. If the list is empty, the zero flag is set and EAX is zero.

Uses

EAX, Flags

See Also

List_Attach, List_Create, List_Get_Next


List_Get_Next
include vmm.inc

mov     esi, List       ; list handle

mov     eax, Node       ; address of node

VMMcall List_Get_Next

jz      empty_list      ; zero flag set if not other nodes in list

mov     [Node], eax     ; address of next node

The List_Get_Next service return the next node in a list. It is used to search a list for a specific element. When the service reaches the end of the list, it returns zero and sets the zero flag.

This service is typically used in conjunction with the List_Get_First service to scan an entire list.

Parameter	Description

List	Specifies the handle identifying a list. The handle must have been previously created using the List_Create service.

Node	Specifies the address of a node in the list. The address must have been previously retrieved using the List_Get_First or List_Get_Next service.

Returns

If the zero flag is clear, the EAX register contains the address of the next node in the list. If there are no other nodes in the list, the zero flag is set and EAX is zero.

Uses

EAX, Flags

See Also

List_Create, List_Get_First


List_Insert
include vmm.inc

mov     esi, List    ; list handle

mov     eax, NewNode ; address of node to insert

mov     ecx, Node    ; address of node to insert after (0 to attach to head)

VMMcall List_Insert

The List_Insert service inserts a node immediately after the specified node in a list. A virtual device can insert a node into any list that has a matching node size. This can be used, for example, to move a node from one list to another.

Parameter	Description

List	Specifies the handle identifying a list. The handle must have been previously created using the List_Create service.

NewNode	Specifies the address of the node to insert. The node must have been previously created using the List_Allocate service.

Node	Specifies the address of a node in the list. The address must have been previously retrieved using the List_Get_First or List_Get_Next service. If this parameter is zero, the service attaches the new node to the head of the list.

Returns

This service has no return value.

Comments

This service inserts the new node between the specified node and the node immediately following the specified node. A virtual device can retrieve the address of the new node by calling the List_Get_Next service and specifying the Node parameter.

Uses

Flags

See Also

List_Attach, List_Attach_Tail


List_Remove
include vmm.inc

mov     esi, List       ; list handle

mov     eax, Node       ; address of node to remove

VMMcall List_Remove_First

jc      not_removed     ; carry flag set if error

The List_Remove service removes the specified node from the list.

Parameter	Description

List	Specifies the handle identifying a list. The handle must have been previously created using the List_Create service.

Node	Specifies the address of the node to remove. The node must have been previously retrieved using the List_Get_First or List_Get_Next service.

Returns

The carry flag is clear if the service is successful. Otherwise, the carry flag is set to indicate an error.

Comments

This service does not deallocate the node. It is up to the virtual device to deallocate the node or attach it to another list.

Uses

EAX, Flags

See Also

List_Create, List_Remove_First


List_Remove_First
include vmm.inc

mov     esi, List       ; list handle

VMMcall List_Remove_First

jz      list_empty      ; zero flag set if list is empty

mov     [Node], eax     ; address of node removed

The List_Remove_First service removes the first node from a list.

Parameter	Description

List	Specifies the handle identifying a list. The handle must have been previously created using the List_Create service.

Returns

If the zero flag is clear, the EAX register contains the address of the node that was removed. If the list is empty, the zero flag is set and EAX contains zero.

Comments

This service does not deallocate the node. It is up to the virtual device to deallocate the node or attach it to another list.

Uses

EAX, Flags

See Also

List_Create, List_Remove


VMM Macros

Assert_VM_Handle	Checks for valid virtual machine handle

Begin_Control_Dispatch	Builds dispatch table for messages

BeginProc	Starts a procedure definition

Begin_Service_Table	Starts a service table

Begin_Touch_1st_Meg	Enables the first megabyte of memory

Begin_VxD_IO_Table	Starts an I/O table

CallRet	Calls a procedure then returns

cCall	Calls a procedure

Client_Ptr_Flat	Converts an V86 or protected-mode address

Control_Dispatch	Dispatches a message to a procedure

Debug_Out	Displays a debugging message and breaks

Declare_Virtual_Device	Defines a virtual device

Dispatch_Byte_IO	Dispatches the specified I/O byte

Dword_Align	Aligns a segment on a doubleword boundary

Emulate_Non_Byte_IO	Emulates word and string input and output

End_Control_Dispatch	Builds dispatch table for messages

EndProc	Marks the end of a procedure definition

End_Service_Table	Ends a service table

End_Touch_1st_Meg	Disables the first megabyte of memory

End_VxD_IO_Table	Ends an I/O table

Fatal_Error	Terminates Windows

IO_Delay	Delays execution of the next instruction

Mono_Out	Writes a message to the secondary display

Mono_Out_At	Writes a message to the secondary display

Pop_Client_State	Restores client registers

Push_Client_State	Saves the client state

Queue_Out	Queues a message

ShiftState	Sets the shift state for a hot key

Trace_Out	Writes a message to the debugging device

VMMcall	Calls a VMM service

VMMjmp	Jumps to a VMM service

VxDcall	Calls a virtual device service

VxD_CODE_ENDS	Defines end of a code segment

VxD_CODE_SEG	Defines a code segment

VxD_DATA_ENDS	Defines end of a data segment

VxD_DATA_SEG	Defines a data segment

VxD_ICODE_ENDS	Defines end of initialization code segment

VxD_ICODE_SEG	Defines an initialization code segment

VxD_IDATA_ENDS	Defines end of initialization data segment

VxD_IDATA_SEG	Defines an initialization data segment

VxDint	Executes a software interrupt

VxD_IO	Adds an entry to an I/O table

VxDjmp	Jumps to a virtual device service

VxD_LOCKED_CODE_ENDS	Defines end of a code segment

VxD_LOCKED_CODE_SEG	Defines a code segment

VxD_LOCKED_DATA_ENDS	Defines end of a data segment

VxD_LOCKED_DATA_SEG	Defines a data segment

VxD_REAL_INIT_ENDS	Defines end of real-mode segment

VxD_REAL_INIT_SEG	Defines a real-mode initialization segment


Assert_VM_Handle
include debug.inc

Assert_VM_Handle VM

The Assert_VM_Handle macro determines whether the specified virtual machine handle is valid.

This macro is only available in the debugging version of Windows.

Parameter	Description

VM	Specifies the virtual machine handle to check.

Returns

This macro has no return value.

Comments

This macro does not return is the handle is not valid.

This macro does not generate code unless the DEBUG symbol is defined. If the macro generates code, the code calls the Debug_Test_Valid_Handle service.

See Also

Debug_Test_Valid_Handle


Begin_Control_Dispatch
include vmm.inc

Begin_Control_Dispatch DeviceName

The Begin_Control_Dispatch macro builds a table for dispatching messages passed to the control procedure for the specified virtual device. This macro is used in conjunction with the Control_Dispatch and End_Control_Dispatch macros.

Parameter	Description

DeviceName	Specifies the name of the virtual device. The macro uses this parameter to construct the label for the control procedure (appends _Control to the end of this name). This control procedure label must also be specified in the Declare_Virtual_Device macro

Returns

This macro has no return value.

Comments

The Control_Dispatch macro can be used without Begin_Control_Dispatch, but then it the programmer's responsibility to declare a procedure in locked code (VxD_LOCKED_CODE_SEG) and clear the carry flag for any messages not processed. The advantage in using Begin_Control_Dispatch macro is when a large number of messages are processed by a device. The macro builds a jump table which usually requires less code then the sequence of compare and jump instructions that are generated when Control_Dispatch is used alone.

Example

The following example builds a complete dispatch table for the virtual device named MyDevice:

Begin_Control_Dispatch MyDevice

Control_Dispatch  Device_Init, MyDeviceInitProcedure

Control_Dispatch  Sys_VM_Init, MyDeviceSysInitProcedure

Control_Dispatch  Create_VM,   MyDeviceCreateVMProcedure

End_Control_Dispatch MyDevice

See Also

Control_Dispatch, Declare_Virtual_Device, End_Control_Dispatch


BeginProc
include vmm.inc

BeginProc ProcName, Attributes

The BeginProc macros marks the start of a procedure having the specified attributes.

Parameter	Description

ProcName	Specifies the name of the procedure to create.

Attributes	Specifies one or more procedure attributes. This parameter can be a combination of the following attributes:

Attribute	Description

ASYNC_SERVICE	Creates an asynchronous service that can be called by other virtual devices. The procedure must be reentrant, must not call synchronous services, and must be defined in a locked segment. Asynchronous services are intended to be called by interrupt handling routines when processing interrupts.

HIGH_FREQ	Specifies a frequently called procedure. The macro aligns the start of the procedure on a doubleword boundary to optimize calls to the procedure.

NO_LOG	Prevents a call to the Log_Call_Proc service from being inserted at the beginning of the procedure. The macro inserts the Log_Call_Proc service only if the DEBUG symbol is defined.

PUBLIC	Creates a global procedure that other procedures in the virtual device can call.

SERVICE	Creates a service that other virtual devices can call. If the DEBUG symbol is defined, the macro inserts a call to the Test_Reenter service at the beginning of the procedure.

If more than one attribute is given, they must be separated by commas.

Returns

This macro has no return value.

See Also

EndProc


Begin_Service_Table
include vmm.inc

Begin_Service_Table DeviceName, DefSegment

The Begin_Service_Table macro marks the start of the service table for a virtual device. A virtual device uses the service table to export the names and addresses of its services. Other virtual devices can use the VxDcall macro to call these services.

Parameter	Description

DeviceName	Specifies the name of the virtual device. This name is used to create a macro, named DeviceName_Service, that is used in the table to define each exported service. See the Comments section for a description of the macro.

DefSegment	Specifies the name of the data segment to place the table. This parameter is optional. If given, the macro uses the DefSegment_LOCKED_DATA_SEG macro to define the segment. Otherwise, it uses the VxD_LOCKED_DATA_SEG macro.

Returns

This macro has no return value.

Comments

A virtual device exports its services by defining the symbol Create_DeviceName_Service_Table before using the Begin_Service_Table macro. Virtual devices that call these service also use the Begin_Service_Table macro but must not define the Create_DeviceName_Service_Table symbol.

The complete service table has the following form:

Begin_Service_Table DeviceName, DefSegment

DeviceName_Service Procedure, LocalSeg

    .

    .

    .

End_Service_Table DeviceName, DefSegment

The DeviceName_Service macro, created by Begin_Service_Table, adds the specified service to the table. A table may have any number of these macros.

The Procedure parameter specifies the name of the service to add to the table. If RESERVED is given, the macro reserves an entry in the table instead adding a procedure.

The LocalSeg parameter specifies which segment contains the procedure. This parameter is optional.

See Also

End_Service_Table, VxD_LOCKED_DATA_SEG


Begin_Touch_1st_Meg
include debug.inc

Begin_Touch_1st_Meg

The Begin_Touch_1st_Meg macro enables the first 1 megabyte of memory for the current virtual machine. Virtual devices use this macro to examine and modify addresses in the first megabyte. This macro is intended to be used for debugging.

This macro has no parameters.

Returns

This macro has no return value.

Comments

This macro does not generate code unless the DEBUG symbol is defined. If the macro generates code, the code calls the Enable_Touch_1st_Meg service.

See Also

Enable_Touch_1st_Meg, End_Touch_1st_Meg


Begin_VxD_IO_Table
include vmm.inc

Begin_VxD_IO_Table TableName

The Begin_VxD_IO_Table macro marks the beginning of an I/O table. Virtual devices use the macro in conjunction with the End_VxD_IO_Table and VxD_IO macros to create a table of I/O callback procedures for the Install_Mult_IO_Handlers service.

Parameter	Description

TableName	Specifies the name of the table. This parameter can be used in subsequent calls to the Install_Mult_IO_Handlers to specify the address of the table.

See Also

Install_Mult_IO_Handlers, End_VxD_IO_Table, VxD_IO


CallRet
include vmm.inc

CallRet Procedure

The CallRet macro either calls or jumps to the specified procedure, depending on whether the DEBUG symbol is defined. If DEBUG is defined, the macro generates a call to the procedure followed by a return instruction. Otherwise, the macro generates a jump to the procedure.

Parameter	Description

Procedure	Specifies the procedure or service to call.

Returns

This macro has no return value.

Comments

This macro is typically used in conjunction with the Log_Proc_Call service to record the path of execution through a virtual device.

See Also

Log_Proc_Call


cCall
include vmm.inc

cCall Procedure, Parameters

The cCall macro pushes the specified parameters on the stack and calls the specified procedure. When the procedure returns, the macro pops the parameters from the stack.

Parameter	Description

Procedure	Specifies the name of the procedure to call. This parameter can be either a local or public procedure, but must be defined within the virtual device making the call.

Parameters	Specifies the parameters to pass to the specified procedure. If more than one parameter is given, they must be separated with commas and enclosed in angle brackets (<>). This parameter is optional.

Returns

The return value is as specified for the given service.

Comments

This macro pushes the parameters using the C-language calling convention, in order from right to left.

See Also

VMMcall, VxDcall


Client_Ptr_Flat
include vmm.inc

Client_Ptr_Flat LinAddr, Segment, Offset

The Client_Ptr_Flat macro converts the specified segment:offset or selector:offset pair into a linear address.

Parameter	Description

LinAddr	Specifies the 32-bit register to receive the linear address.

Segment	Specifies the client segment register containing the segment address or selector to convert.

Offset	Specifies the register containing the address offset to convert. If this optional parameter is not given, the macro converts the address using address offset 0.

Returns

The register specified by LinAddr contains the linear address. The register contains -1 if the specified selector is invalid.

Example

This example converts the address Client_DS:Client_DX and places the corresponding linear address in the EAX register.

Client_Ptr_Flat eax, DS, DX

See Also

Map_Flat


Control_Dispatch
include vmm.inc

Control_Dispatch Message, Procedure

The Control_Dispatch macro dispatches the given control message to the specified procedure.

Parameter	Description

Message	Specifies a control message. It can be one of the following:

Message	Description

Begin_PM_App	A protected-mode application is starting

Close_VM_Notify	A virtual machine is closing

Create_VM	A virtual machine is being created

Critical_Reboot_Notify	System is rebooting (interrupt disabled)

Debug_Query	Requests for virtual device's debugging interface

Destroy_VM	A virtual machine is being destroyed

Device_Init	Virtual devices initializing (interrupts enabled)

Device_Reboot_Notify	System is rebooting (interrupts enabled)

End_PM_App	A protected-mode application is ending

Init_Complete	All virtual devices have initialized

Power_Event	Power is being suspended or resumed

Reboot_Processor	Virtual device must reboot system if it can

Set_Device_Focus	A virtual device is taking the focus

Sys_Critical_Exit	System is terminating (interrupt disabled)

Sys_Critical_Init	Virtual devices initializing (interrupts disabled)

Sys_VM_Init	System VM is being created

Sys_VM_Terminate	System VM is being destroyed

System_Exit	System is terminating (interrupts enabled)

VM_Critical_Init	Virtual machine being created (interrupts disabled)

VM_Init	Virtual machine being created (interrupts enabled)

VM_Not_Executeable	Virtual machine being destroyed

VM_Resume	Virtual machine execution resumed

VM_Suspend	Virtual machine execution suspended

VM_Terminate	Virtual machine begin destroyed

Procedure	Specifies the name of the procedure to dispatch the message to.

Returns

This macro has no return value.

Comments

This macro is typically used in conjunction with the Begin_Control_Dispatch and End_Dispatch_Table macro to build a

The Control_Dispatch macro can be used without the Begin_Control_Dispatch macro, but becomes the programmer's responsibility to declare a procedure in locked code (VxD_LOCKED_CODE_SEG) and clear the carry flag for any messages not processed.

See Also

Begin_Control_Dispatch, End_Control_Dispatch


Debug_Out
include debug.inc

Debug_Out String

The Debug_Out macro writes the specified string to the debugging device and breaks execution by executing an int 1 instruction if the debugging version of Windows is installed.

Parameter	Description

String	Specifies the string to display. The string must be enclosed in double quotation marks. The string can contain register placeholders in the same forms as described for the Out_Debug_String service.

Returns

This service has no return value.

Comments

The macro calls the Test_Debug_Installed service to determine whether to execute the int 1 instruction. If the debugging version is not installed, the instruction is skipped.

The assembler generates code for the macro only if the constant DEBUG is defined before including the DEBUG.INC file.

See Also

Out_Debug_String, Test_Debug_Installed


Declare_Virtual_Device
include vmm.inc

Declare_Virtual_Device Name, MajorVer, MinorVer, CtrlProc, DeviceNum,

                       InitOrder, V86Proc, PMProc

The Declare_Virtual_Device macro defines the name, device number, control procedure, and other attributes of a virtual device. Every virtual device must use the Declare_Virtual_Device macro.

Parameter	Description

Name	Specifies the name of the virtual device.

MajorVer	Specifies the major version number for the virtual device.

MinorVer	Specifies the minor version number for the virtual device.

CtrlProc	Specifies the control procedure for the virtual device. The control procedure handles all system control messages sent to the virtual device. For most virtual devices, this parameter is the name of the procedure created by the Begin_Control_Dispatch macro.

DeviceNum	Specifies the device identifier for the virtual device. If the virtual device replaces an existing virtual device, the device identifier must be one of the following:

Value	Meaning

APM_Device_ID	Power management

BiosHook_Device_ID	BIOS interrupt hook

BIOSXlat_Device_ID	BIOS translation

BlockDev_Device_ID	Block devices

Debug_Device_ID	Debug device

DOSMGR_Device_ID	MS-DOS manager

DOSNET_Device_ID	MS-DOS networks

EBIOS_Device_ID	EBIOS

Int13_Device_ID	Interrupt 13h hook

MCA_POS_Device_ID	MCA_POS device

PageFile_Device_ID	Paging file

PageSwap_Device_ID	Page swap

Parity_Device_ID	Parity

Reboot_Device_ID	Reboot

SCSI_Device_ID	SCSI device

SCSIFD_Device_ID	SCSI FastDisk device

SHELL_Device_ID	386-enhanced mode Windows shell

TSRLoad_Device_ID	TSR instance utility

Undefined_Device_ID	Reserved

V86MMGR_Device_ID	V86 mode memory manager

VCD_Device_ID	Communications ports

VDD2_Device_ID	Secondary display adapter

VDD_Device_ID	Display adapter

VDMAD_Device_ID	DMA

VFD_Device_ID	Floppy disk

VKD_Device_ID	Keyboard

VMCPD_Device_ID	Math coprocessor

VMD_Device_ID	Mouse or pointing device

VMM_Device_ID	Reserved; do not use

VMPoll_Device_ID	Virtual machine polling

VNETBIOS_Device_ID	Network BIOS

VPD_Device_ID	Printer ports

VPEND_Device_ID	Pen device

VPICD_Device_ID	Programmable interrupt controller

VPROD_Device_ID	Profiling

VSD_Device_ID	Sound adapter

VTD_Device_ID	Timer

WINDEBUG_Device_ID	Windows debugging

WINLOAD_Device_ID	Windows loader

If the type of virtual device is new, a new OEM virtual device identifier must be explictly requested from Microsoft. For more information, see the Installation and Update Guide.

InitOrder	Specifies when the virtual device should be initialized relative to other virtual devices. For an existing device type, this parameter can be one of the following values:

APM_Init_Order

BiosHook_Init_Order

BIOSXlat_Init_Order

BlockDev_Init_Order

Debug_Init_Order

DOSMGR_Init_Order

DOSNET_Init_Order

EBIOS_Init_Order

Int13_Init_Order

MCA_POS_Init_Order

PageFile_Init_Order

PageSwap_Init_Order

Parity_Init_Order

Reboot_Init_Order

SCSIFD_Init_Order

SCSIMaster_Init_Order

SHELL_Init_Order

Undefined_Init_Order

V86MMGR_Init_Order

VCD_Init_Order

VDD_Init_Order

VDMAD_Init_Order

VFD_Init_Order

VKD_Init_Order

VMCPD_Init_Order

VMD_Init_Order

VMM_Init_Order

VMPoll_Init_Order

VNETBIOS_Init_Order

VPD_Init_Order

VPICD_Init_Order

VPROD_Init_Order

VSD_Init_Order

VTD_Init_Order

WINDEBUG_Init_Order

WINLOAD_Init_Order

V86Proc	Specifies the V86-mode API procedure. This procedure processes any calls to the virtual device made by V86-mode applications running in a virtual machine. This parameter is optional.

PMProc	Specifies the protected-mode API procedure. This procedure processes any calls to the virtual device made by protected-mode applications running in a virtual machine. This parameter is optional.

Returns

This macro has no return value.

See Also

Begin_Control_Dispatch


Dispatch_Byte_IO
include vmm.inc

Dispatch_Byte_IO In_Proc, Out_Proc

The Dispatch_Byte_IO macro checks the size of the I/O request and dispatches the request to either the Simulate_IO service or to the specified single-byte input or output procedure. I/O callback procedures use this macro to simplify processing of I/O requests.

Parameter	Description

In_Proc	Specifies the name of the procedure to carry out a single-byte input operation. If this parameter is the Fall_Through keyword, the macro ignores input operations.

Out_Proc	Specifies the name of the procedure to carry out a single-byte output operation. If this parameter is the Fall_Through keyword, the macro ignores output operations.

Returns

This macro has no return value.

Comments

The EAX, EBX, ECX, EDX, and EBP registers must contain values specified as valid input parameters for the Simulate_IO service. Dispatch_Byte_IO checks the ECX register for the I/O type. If this type specifies an I/O request that is larger than a byte, the macro jumps to the Simulate_IO service.

See Also

Emulate_Non_Byte_IO, Simulate_IO


Dword_Align
include vmm.inc

Dword_Align SegName

The Dword_Align macro aligns the specified segment on a doubleword boundary by inserting nop instructions.

Parameter	Description

SegName	Specifies the name of the segment to align. This parameter can be _TEXT, _ITEXT, or _LTEXT.

Returns

This macro has no return value.


Emulate_Non_Byte_IO
include vmm.inc

Emulate_Non_Byte_IO

The Emulate_Non_Byte_IO macro checks the size of the I/O request and jumps to the Simulate_IO service if the request is larger than a byte. I/O callback procedures use this macro to simplify processing of I/O requests.

This macro has no parameters.

Returns

This macro has no return value.

Comments

The EAX, EBX, ECX, EDX, and EBP registers must contain values specified as valid input parameters for the Simulate_IO service. Emulate_Non_Byte_IO checks the ECX register for the I/O type. If this type specifies an I/O request that is larger than a byte, the macro jumps to the Simulate_IO service.

See Also

Dispatch_Byte_IO, Simulate_IO


End_Control_Dispatch
include vmm.inc

End_Control_Dispatch DeviceName

The End_Control_Dispatch macro marks the end of a dispatch table for a virtual device. This macro is used in conjunction with the Control_Dispatch and Begin_Control_Dispatch macros to build the table.

Parameter	Description

DeviceName	Specifies the name of the virtual device. This name must have been used with the Begin_Control_Dispatch macro that started the table.

Returns

This macro has no return value.

See Also

Begin_Control_Dispatch, Control_Dispatch


EndProc
include vmm.inc

EndProc ProcName

The EndProc macro marks the end of a procedure definition. This macro is used in conjunction with the BeginProc macro to define a procedure in a virtual device.

Parameter	Description

ProcName	Specifies the name of the procedure. This name must have been used in the BeginProc macro that started the procedure definition.

Returns

This macro has no return value.

See Also

BeginProc


End_Service_Table
include vmm.inc

End_Service_Table DeviceName, DefSegment

The End_Service_Table macro marks the end of the service table for a virtual machine. This macro is used in conjunction with the Begin_Service_Table macro to create a service table.

Parameter	Description

DeviceName	Specifies the name of the virtual device. This name must be the same as specified by the corresponding Begin_Service_Table macro.

DefSegment	Specifies the name of the data segment to place the table. This parameter is optional. If given, it must be the same as specified by the corresponding Begin_Service_Table macro.

Returns

This macro has no return value.

See Also

Begin_Service_Table


End_Touch_1st_Meg
include debug.inc

End_Touch_1st_Meg

The End_Touch_1st_Meg macro disables the first 1 megabyte of memory for the current virtual machine. Virtual devices use this macro in conjunction with the Begin_Touch_1st_Meg macro to examine and modify addresses in the first megabyte. This macro is intended to be used for debugging.

This macro has no parameters.

Returns

This macro has no return value.

Comments

This macro does not generate code unless the DEBUG symbol is defined. If the macro generates code, the code calls the Disable_Touch_1st_Meg service.

See Also

Begin_Touch_1st_Meg, Disable_Touch_1st_Meg


End_VxD_IO_Table
include vmm.inc

End_VxD_IO_Table TableName

The End_VxD_IO_Table macro marks the end of an I/O table. Virtual devices use the macro in conjunction with the Begin_VxD_IO_Table and VxD_IO macros to create a table of I/O callback procedures for the Install_Mult_IO_Handlers service.

Parameter	Description

TableName	Specifies the name of the I/O table. This parameter must have been previously defined in a matching Begin_VxD_IO_Table macro.

See Also

Begin_VxD_IO_Table


Fatal_Error
include vmm.inc

Fatal_Error Msg_Ptr, Exit_Flags

The Fatal_Error macro calls the Fatal_Error_Handler service which terminates Windows. A virtual device typically calls this macro in response to an unrecoverable error. The macro passes the Msg_Ptr and Exit_Flags parameters (if given) to Fatal_Error_Handler.

Parameter	Description

Msg_Ptr	Points to a zero-terminated string. This parameter is optional.

Exit_Flags	Specifies the exit flags. This optional parameter can be a combination of the following values:

Value	Meaning

EF_Hang_On_Exit	Hangs the system on a fatal exit.

Returns

This macro never returns.

Example

The following example exits Windows without displaying an error message:

Fatal_Error

The following example exits Windows and prints the error message pointed to by My_Err_Msg:

Fatal_Error OFFSET32 My_Err_Msg

See Also

Fatal_Error_Handler


IO_Delay
include vmm.inc

IO_Delay

The IO_Delay macro delays the execution of the next instruction so that an I/O device has time to carry out an I/O operation.

This macro has no parameters.

Returns

This macro has no return value.

Comments

This macro generates a jmp instruction to the next instruction.


Mono_Out
include debug.inc

Mono_Out String, nocrlf

The Mono_Out macro calls the Out_Mono_String service to display the given string.

Parameter	Description

String	Specifies the string to display. The string must be enclosed in double quotation marks. The string can contain register placeholders in the same forms as described for the Out_Mono_String service.

nocrlf	Specifies whether the macro should not append a newline and carriage return character combination to the end of the string. If the parameter is not given, the macro appends the character combination by default.

Returns

This macro has no return value.

Comments

The assembler generates code for the macro only if the constant DEBUG is defined before including the DEBUG.INC file.

Example

The following example writes a string to the secondary display device:

Mono_Out "Element not found"

The following example writes a string containing the value of the AX register to the debugging device:

Mono_Out "AX value is #AX"

See Also

Out_Mono_String


Mono_Out_At
include debug.inc

Mono_Out_At Row, Column, String, nocrlf

The Mono_Out_At macro calls the Set_Mono_Cur_Pos service to position the cursor, then calls the Out_Mono_String service to display the given string.

Parameter	Description

Row	Specifies the row to place the first character of the string.

Column	Specifies the column in which to place the first character of the string.

String	Specifies the string to display. The string must be enclosed in double quotation marks. The string can contain register placeholders in the same forms as described for the Out_Mono_String service.

nocrlf	Specifies whether the macro should not append a newline and carriage return character combination to the end of the string. If the parameter is not given, the macro appends the character combination by default.

Returns

This macro has no return value.

Comments

The assembler generates code for the macro only if the constant DEBUG is defined before including the DEBUG.INC file.

Example

The following example writes a string starting at the position (10,10) on the secondary display device:

Mono_Out_At 10,10,"Element not found"

See Also

Out_Mono_String, Set_Mono_Cur_Pos


Pop_Client_State
include vmm.inc

Pop_Client_State

The Pop_Client_State macro restores the client registers for the virtual machine.

This macro has no parameters.

Returns

This macro has no return value.

Comments

This macro must not be used unless the Push_Client_State macro was previously used to save the client registers.

See Also

Push_Client_State


Push_Client_State
include vmm.inc

Push_Client_State

The Push_Client_State macro copies the client state to the protected-mode stack.

This macro has no parameters.

Returns

This macro has no return value.

Comments

This macro reserves space on the stack for the client registers.

A virtual device must use the Pop_Client_State macro to restore the client registers, and free the reserve stack space.

See Also

Pop_Client_State


Queue_Out
include debug.inc

Queue_Out String, Value1, Value2

The Queue_Out macro calls the Queue_Debug_String service to queue the given string for display at a later time.

Parameter	Description

String	Specifies the string to display. The string must be enclosed in double quotation marks. The string can contain register placeholders in the same forms as described for the Queue_Debug_String service.

Value1	Specifies a value to queue with the string. If the string contains the #EAX or ?EAX placeholder, this value is used when the string is displayed.

Value2	Specifies a value to queue with the string. If the string contains the #EBX or ?EBX placeholder, this value is used when the string is displayed.

Returns

This macro has no return value.

Comments

The assembler generates code for the macro only if the constant DEBUG is defined before including the DEBUG.INC file.

Example

The following example queues a string:

Queue_Out "Element not found"

The following example queues a string containing the value of the AX register to the debugging device:

Queue_Out "AX value is #AX", AX

See Also

Queue_Debug_String


ShiftState
include vmm.inc

ShiftState Mask, Compare

The ShiftState macro sets the EBX register with the shift state mask and shift state compare value required for a call to the VKD_Define_Hot_Key service.

Parameter	Description

Mask	Specifies the shift state bits that should be excluded before the compare is done.

Compare	Specifies the value to compare

Returns

See Also

VKD_Define_Hot_Key


Trace_Out
include debug.inc

Trace_Out String, nocrlf

The Trace_Out macro calls the Out_Debug_String service to display the given string.

Parameter	Description

String	Specifies the string to display. The string must be enclosed in double quotation marks. The string can contain register placeholders in the same forms as described for the Out_Debug_String service.

nocrlf	Specifies whether the macro should not append a newline and carriage return character combination to the end of the string. If the parameter is not given, the macro appends the character combination by default.

Returns

This macro has no return value.

Comments

The assembler generates code for the macro only if the constant DEBUG is defined before including the DEBUG.INC file.

Example

The following example writes a string to the debugging device:

Trace_Out "Element not found"

The following example writes a string containing the value of the AX register to the debugging device:

Trace_Out "AX value is #AX"

See Also

Out_Debug_String


VMMcall
include vmm.inc

VMMcall Service, Parameters

The VMMcall macro pushes the specified parameters on the stack, creates a dynamic link to the specified VMM service, and calls the service. When the service returns, the macro pops the parameters from the stack.

Parameter	Description

Service	Specifies the name of the service to link to and call. This parameter can be any service that is explicitly defined in the service table for the VMM.

Parameters	Specifies the parameters to pass to the specified service. If more than one parameter is given, they must be separated with commas and enclosed in angle brackets (<>). This parameter is optional.

Returns

The return value is as specified for the given service.

Comments

This macro pushes the parameters using the C-language calling convention, in order from right to left.

See Also

VxDcall, VMMjmp


VMMjmp
include vmm.inc

VMMjmp Service

The VMMjmp macro creates a dynamic link to the specified VMM service then jumps to the service.

Parameter	Description

Service	Specifies the name of the service to link and jump to. This parameter can be any service that is explicitly defined in the service table for the VMM.

Returns

This macro has no return value.

Comments

If the DEBUG symbol is defined, the macro calls the specified service then immediately returns when the service returns. This form of the macro is typically used in conjunction with the Log_Proc_Call service to record the path of execution through a virtual device while debugging.

See Also

VMMcall, VxDjmp


VxDcall
include vmm.inc

VxDcall Service

The VxDcall macro pushes the specified parameters on the stack, creates a dynamic link to the specified virtual device service, and calls the service. When the service returns, the macro pops the parameters from the stack.

Parameter	Description

Service	Specifies the name of the service to link to and call. This parameter can be any service that is explicitly defined in the service table for a given virtual device.

Parameters	Specifies the parameters to pass to the specified service. If more than one parameter is given, they must be separated with commas and enclosed in angle brackets (<>). This parameter is optional.

Returns

The return value is as specified for the given service.

Comments

This macro pushes the parameters using the C-language calling convention, in order from right to left.

See Also

VMMcall, VxDjmp


VxD_CODE_ENDS
include vmm.inc

VxD_CODE_ENDS

The VxD_CODE_ENDS macro defines the end of a code segment. Virtual devices use this macro with in conjunction with the VxD_CODE_SEG macro to create segments for noninitialization code.

This macro has no parameters.

Returns

This macro has no parameters.

Comments

This macro is equal to the VxD_LOCKED_CODE_ENDS macro.

See Also

VxD_CODE_SEG, VxD_LOCKED_CODE_ENDS


VxD_CODE_SEG
include vmm.inc

VxD_CODE_SEG

The VxD_CODE_SEG macro defines the start of a code segment. Virtual devices use this segment for all code that is not explicitly for initialization of the device.

Comments

This macro creates a 32-bit segment named _LTEXT. The segment is assembled for flat model memory so segment registers CS, DS, ES, and SS are assumed to be equal.

This macro is equal to the VxD_LOCKED_CODE_SEG macro.

See Also

VxD_CODE_ENDS, VxD_ICODE_SEG, VxD_DATA_SEG, VxD_LOCKED_CODE_SEG


VxD_DATA_ENDS
include vmm.inc

VxD_DATA_ENDS

The VxD_DATA_ENDS macro defines the end of a data segment. Virtual devices use this macro with in conjunction with the VxD_DATA_SEG macro to create segments for noninitialization data.

This macro has no parameters.

Returns

This macro has no parameters.

Comments

This macro is equal to the VxD_LOCKED_DATA_ENDS macro.

See Also

VxD_DATA_SEG, VxD_LOCKED_DATA_ENDS


VxD_DATA_SEG
include vmm.inc

VxD_DATA_SEG NoAlign

The VxD_DATA_SEG macro defines the start of a data segment. Virtual devices use this segment for all data that is not explicitly for initialization of the device.

Parameter	Description

NoAlign	Specifies that data be aligned at the next byte. If this optional parameter is not given, the macro aligns data at the next available doubleword.

Comments

This macro creates a 32-bit segment named _LDATA.

This macro is equal to the VxD_LOCKED_DATA_SEG macro.

See Also

VxD_CODE_SEG, VxD_DATA_ENDS, VxD_IDATA_SEG, VxD_LOCKED_DATA_SEG


VxD_ICODE_ENDS
include vmm.inc

VxD_ICODE_ENDS

The VxD_ICODE_ENDS macro defines the end of an initialization code segment. Virtual devices use this macro with in conjunction with the VxD_ICODE_SEG macro to create initialization code.

This macro has no parameters.

Returns

This macro has no parameters.

See Also

VxD_ICODE_SEG


VxD_ICODE_SEG
include vmm.inc

VxD_ICODE_SEG

The VxD_ICODE_SEG macro defines the start of an initialization code segment. Virtual devices typically use this segment for code that initializes the corresponding device. The system discards the segment after the initialization is complete (after the Init_Complete message has been processed by all virtual devices).

Comments

This macro creates a 32-bit segment named _ITEXT. The segment is assembled for flat model memory so segment registers CS, DS, ES, and SS are assumed to be equal.

See Also

VxD_CODE_SEG, VxD_ICODE_ENDS, VxD_IDATA_SEG


VxD_IDATA_ENDS
include vmm.inc

VxD_IDATA_ENDS

The VxD_IDATA_ENDS macro defines the end of an initialization data segment. Virtual devices use this macro with in conjunction with the VxD_IDATA_SEG macro to create initialization data.

This macro has no parameters.

Returns

This macro has no parameters.

See Also

VxD_IDATA_SEG


VxD_IDATA_SEG
include vmm.inc

VxD_IDATA_SEG

The VxD_IDATA_SEG macro defines the start of an initialization data segment. Virtual devices typically use this segment for data used to initialize the corresponding device. The system discards the segment after the initialization is complete (after the Init_Complete message has been processed by all virtual devices).

Comments

This macro creates a 32-bit segment named _IDATA.

See Also

VxD_DATA_SEG, VxD_IDATA_ENDS, VxD_ICODE_SEG


VxDint
include vmm.inc

VxDint Int_Number

The VxDint macro executes the specified software interrupt. This macro pushes the interrupt number on the stack and calls the Exec_VxD_Int service.

Parameter	Description

Int_Number	Specifies the number of the software interrupt to execute.

Returns

One or more registers may contain return values depending the function of the specified interrupt.

See Also

Exec_VxD_Int


VxD_IO
include vmm.inc

VxD_IO  Port, IOCallback

The VxD_IO macro adds an I/O callback procedure and I/O port number to an I/O table. Virtual devices use the macro in conjunction with the Begin_VxD_IO_Table and End_VxD_IO_Table macros to create a table of I/O callback procedures for the Install_Mult_IO_Handlers service.

Parameter	Description

Port	Specifies the number of the I/O port to be trapped.

IOCallback	Specifies the name of the I/O callback procedure. See the Comments section for information about this procedure.

Returns

This service has no return value.

Comments

The I/O table can contain any number of VxD_IO macros. Each macro must specify an unique I/O port number, but the same I/O callback procedure can be assigned to more than one port.

After a virtual device installs the callback procedures, the system calls a procedure whenever a program in the virtual machine attempts to access the corresponding port. The system calls the procedure as follows:

mov     ebx, VM             ; current VM handle

mov     ecx, IOType         ; type of I/O

mov     edx, Port           ; port number

mov     ebp, OFFSET32 crs   ; points to a Client_Reg_Struc

mov     eax, Data           ; output data (if I/O type is output)

call    [IOCallback]

mov     [Data], eax         ; input data (if I/O type is input)

The VM parameter specifies the current virtual machine, Port specifies the I/O port, and crs points to a Client_Reg_Struc structure containing the register contents for the current virtual machine.

The IOType parameter specifies the type of input or output operation requested and determines whether the callback procedure receives data in the EAX register or must return data in the EAX register. The IOType parameter can be a combination of the following values:

Value	Meaning

Byte_Input	Input a single byte; place in AL if String_IO not given.

Byte_Output	Output a single byte from AL if String_IO not given.

Word_Input	Input a word; place in AX if String_IO not given.

Word_Output	Output a word from AX if String_IO not given.

Dword_Input	Input a double word; place in EAX if String_IO not given.

Dword_Output	Output a double word from EAX if String_IO not given.

String_IO	Input or output a string. The high 16-bits specifies segment address of buffer containing the string to output or to receive the string input.

Rep_IO	Repeat the input or output string operation the number of times specified by the Client_CX field in the Client_Reg_Struc structure.

Addr_32_IO	Use 32-bit address offsets for input or output string operations. If this value is not given, the 16-bit offsets are used.

Reverse_IO	Decrement string address on each input or output operation. If this value is not given, the string address is incremented on each operation.

In memory, an I/O table consists of a VxD_IOT_Hdr structure followed by one or more VxD_IO_Struc structures. The first word in the table specified the number of entries. Each entry consists of a word specifying the port number and a double word specifying the 32-bit offset of the callback procedure.

See Also

Begin_VxD_IO_Table, End_VxD_IO_Table, Install_Mult_IO_Handlers


VxDjmp
include vmm.inc

VxDjmp Service

The VMMjmp macro creates a dynamic link to the specified virtual device service then jumps to the service.

Parameter	Description

Service	Specifies the name of the service to link and jump to. This parameter can be any service that is explicitly defined in the service table for a virtual device.

Returns

This macro has no return value.

Comments

If the DEBUG symbol is defined, the macro calls the specified service then immediately returns when the service returns. This form of the macro is typically used in conjunction with the Log_Proc_Call service to record the path of execution through a virtual device while debugging.

See Also

VMMjmp, VxDcall


VxD_LOCKED_CODE_ENDS
include vmm.inc

VxD_LOCKED_CODE_ENDS

The VxD_LOCKED_CODE_ENDS macro defines the end of a code segment. Virtual devices use this macro with in conjunction with the VxD_LOCKED_CODE_SEG macro to create segments for noninitialization code.

This macro has no parameters.

Returns

This macro has no parameters.

Comments

This macro is equal to the VxD_CODE_ENDS macro.

See Also

VxD_LOCKED_CODE_SEG, VxD_CODE_ENDS


VxD_LOCKED_CODE_SEG
include vmm.inc

VxD_LOCKED_CODE_SEG

The VxD_LOCKED_CODE_SEG macro defines the start of a code segment. Virtual devices use this segment for all code that is not explicitly for initialization of the device.

Comments

This macro creates a 32-bit segment named _LTEXT. The segment is assembled for flat model memory so segment registers CS, DS, ES, and SS are assumed to be equal.

This macro is equal to the VxD_CODE_SEG macro.

See Also

VxD_CODE_SEG, VxD_LOCKED_CODE_ENDS


VxD_LOCKED_DATA_ENDS
include vmm.inc

VxD_LOCKED_DATA_ENDS

The VxD_LOCKED_DATA_ENDS macro defines the end of a data segment. Virtual devices use this macro with in conjunction with the VxD_LOCKED_DATA_SEG macro to create segments for noninitialization data.

This macro has no parameters.

Returns

This macro has no parameters.

Comments

This macro is equal to the VxD_DATA_ENDS macro.

See Also

VxD_DATA_ENDS, VxD_LOCKED_DATA_SEG


VxD_LOCKED_DATA_SEG
include vmm.inc

VxD_LOCKED_DATA_SEG NoAlign

The VxD_LOCKED_DATA_SEG macro defines the start of a data segment. Virtual devices use this segment for all data that is not explicitly for initialization of the device.

Parameter	Description

NoAlign	Specifies that data be aligned at the next byte. If this optional parameter is not given, the macro aligns data at the next available doubleword.

Comments

This macro creates a 32-bit segment named _LDATA.

This macro is equal to the VxD_DATA_SEG macro.

See Also

VxD_DATA_SEG, VxD_LOCKED_DATA_ENDS


VxD_REAL_INIT_ENDS
include vmm.inc

VxD_REAL_INIT_ENDS

The VxD_REAL_INIT_ENDS macro defines the end of a real-mode initialization segment. Virtual devices use this macro with in conjunction with the VxD_REAL_INIT_SEG macro to create initialization code for real-mode execution.

This macro has no parameters.

Returns

This macro has no parameters.

See Also

VxD_REAL_INIT_SEG


VxD_REAL_INIT_SEG
include vmm.inc

VxD_REAL_INIT_SEG

The VxD_REAL_INIT_SEG macro defines the start of a real-mode initialization segment. Virtual devices typically use this segment for code that initializes the corresponding device before Windows changes to protected-mode execution. The system discards the segment after the initialization is complete.

Comments

This macro creates a 16-bit segment named _RCODE. The segment is assembled for the real-mode tiny model memory so segment registers CS, DS, ES, and SS are assumed to be equal.

See Also

VxD_ICODE_SEG, VxD_REAL_INIT_ENDS


VMM Control Messages

Begin_Message_Mode	Starts message mode processing

Begin_PM_App	Starts a protected-mode application

Close_VM_Notify	Notification for closing a virtual machine

Create_VM	Creates a virtual machine

Crit_Reboot_Notify	Signals a pending system reboot

Debug_Query	Displays and processes debugging commands

Destroy_VM	Destroys a virtual machine

Device_Init	Initializes a virtual device

Device_Reboot_Notify	Signals a pending system restart

End_Message_Mode	Ends message mode processing

End_PM_App	Ends a protected-mode application

Init_Complete	Completes virtual device initialization

Power_Event	Signals a change in power availability

Query_Destroy	Queries for permission to destroy virtual machine

Reboot_Processor	Restarts the computer

Set_Device_Focus	Sets the device focus

Sys_Critical_Exit	Exits critical virtual devices

Sys_Critical_Init	Initializes critical virtual devices

Sys_VM_Init	Initializes system virtual machine

Sys_VM_Terminate	Terminates the system virtual machine

System_Exit	Exits the system

VM_Critical_Init	Initializes critical virtual devices

VM_Init	Initializes devices for a virtual machine

VM_Not_Executeable	Identifies a nonexecutable virtual machine

VM_Resume	Resumes execution of the virtual machine

VM_Suspend	Suspends execution of a virtual machine

VM_Terminate	Terminates a virtual machine


Begin_Message_Mode
include vmm.inc

mov     ebx, VM                 ; VM handle

mov     eax, Begin_Message_Mode

VMMcall System_Control

The Begin_Message_Mode message notifies the virtual display, keyboard, and mouse devices to prepare to display messages and read input from the keyboard. The system sends this message if Windows cannot display the requested warning or error message.

Parameter	Description

VM	Specifies a handle identifying the virtual machine entering message mode.

Returns

The carry flag must be clear.

Comments

This message is usually processed only by the virtual keyboard, mouse, and display devices.

Uses

Flags

See Also

End_Message_Mode


Begin_PM_App
include vmm.inc

mov     ebx, VM              ; current VM handle

mov     edx, Flags           ; flags

mov     edi, OFFSET32 acb    ; points to Application Control Block

mov     eax, Begin_PM_App

VMMcall System_Control

The Begin_PM_App message notifies the virtual device that the system is starting a protected-mode application.

Parameter	Description

VM	Specifies a handle identifying the current virtual machine.

Flags	Specifies the operation flags. It can be the following value:

Value	Meaning

BPA_32_Bit	Application has 32-bit segments. If this value is not given, the application has 16-bit segments.

All other values are reserved.

abc	Points to an application control block.

Returns

The carry flag is clear if the virtual device can support the protected-mode application. Otherwise, the carry flag is set to indicate an error.

Uses

Flags

See Also

End_PM_App


Close_VM_Notify
include vmm.inc

mov     ebx, VM             ; current VM handle

mov     edx, Flags          ; flags

mov     eax, Close_VM_Notify

VMMcall System_Control

The Close_VM_Notify message notifies a virtual device that the Close_VM service has been called and the specified virtual machine is terminating.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to close.

Flags	Specifies the operation flags. This parameter can be the following value:

Value	Meaning

CVNF_Crit_Close	The virtual machine has not released the critical section.

All other values are reserved.

Returns

The carry flag is set if the virtual device supports termination of the virtual machine. Otherwise, the carry flag is set to indicate an error.

Uses

Flags

See Also

Close_VM


Create_VM
include vmm.inc

mov     ebx, VM        ; new VM handle

mov     eax, Create_VM

VMMcall System_Control

The Create_VM message notifies a virtual machine that the system is creating a new virtual machine. Virtual devices typically initialize data associated with the virtual machine, such as data in the control block for the virtual machine.

Parameter	Description

VM	Specifies a handle identifying the new virtual machine.

Returns

The carry flag is clear if the virtual device can support the new virtual machine. Otherwise, the carry flag is set to indicate an error and prevent the system from creating the virtual machine.

Uses

Flags

See Also

Destroy_VM


Crit_Reboot_Notify
include vmm.inc

mov     eax, Crit_Reboot_Notify

VMMcall System_Control

The Crit_Reboot_Notify message notifies a virtual device that the system is about to restart. Virtual devices typically prepare for restarting by cleaning up data or resetting devices. The system disables interrupts before it sends this message.

This message has no parameters.

Returns

The carry flag must be clear.

Uses

Flags

See Also

Device_Reboot_Notify


Debug_Query
include vmm.inc

mov     eax, Debug_Query

VMMcall System_Control

The Debug_Query message directs the virtual device to enable its debugging commands (if nay). The virtual device should display a list of debugging commands, then read the debugging device for command input from the user. The system sends this message when the user enters a virtual-device command (a period followed by the name of the virtual device) at the WDEB386 prompt.

This message has no parameters.

Returns

The carry flag must be clear.

Comments

This message is intended to be used only in debugging versions of the virtual device. Support for this message should be removed from the final virtual device.

Uses

Flags


Destroy_VM
include vmm.inc

mov     ebx, VM         ; VM handle

mov     eax, Destroy_VM

VMMcall System_Control

The Destroy_VM message notifies the virtual device that the system has destroyed the virtual machine. Virtual devices typically remove any data associated with the specified virtual machine.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to destroy.

Returns

The carry flag must be clear.

Comments

The virtual device must not call the Simulate_Int or Exec_Int service in the specified virtual machine.

Considerable time can elapse between receipt of the VM_Not_Executeable message and this message.

Uses

Flags

See Also

Create_VM, VM_Not_Executeable


Device_Init
include vmm.inc

mov     ebx, SysVM                  ; system VM handle

mov     esi, OFFSET32 CommandTail   ; points to WIN386 command tail

mov     eax, Device_Init

VMMcall System_Control

The Device_Init message directs the virtual device to initialize itself. The virtual device typically allocates memory for a device-specific section in the control block, allocates other memory areas, hooks interrupts and I/O ports, and specifies instance data.

Parameter	Description

SysVM	Specifies a handle identifying the system virtual machine.

CommandTail	Points to the command tail retrieved from the program segment prefix (PSP) of WIN386.EXE. The first byte in the command tail specifies the length in bytes of the tail.

Returns

The carry flag is clear if the virtual device is initialized successfully. Otherwise, the carry flag is set to indicate an error and prevent the system from loading the virtual device.

Comments

The virtual device should allocate a device-specific section in the control block of the system virtual machine and initialize the section.

The virtual device can call the Simulate_Int and Exec_Int services in the system virtual machine.

Uses

Flags

See Also

Init_Complete, Sys_Critical_Init


Device_Reboot_Notify
include vmm.inc

mov     eax, Device_Reboot_Notify

VMMcall System_Control

The Device_Reboot_Notify message notifies the virtual device that the system is about to restart. Interrupts remain enabled while virtual devices process this message.

This message has no parameters.

Returns

The carry flag must be clear.

Uses

Flags

See Also

Crit_Reboot_Notify


End_Message_Mode
include vmm.inc

mov     ebx, VM          ; VM handle

mov     eax, End_Message_Mode

VMMcall System_Control

The End_Message_Mode message directs the virtual device to end message mode processing.

Parameter	Description

VM	Specifies a handle identifying the virtual machine leaving message mode.

Returns

The carry flag must be clear.

Uses

Flags

See Also

Begin_Message_Mode


End_PM_App
include vmm.inc

mov     ebx, VM             ; current VM handle

mov     edi, OFFSET32 acb   ; points to Application Control Block

mov     eax, End_PM_App

VMMcall System_Control

The End_PM_App message notifies the virtual device that the system is terminating a protected-mode application.

Parameter	Description

VM	Specifies a handle identifying the current virtual machine.

abc	Points to an application control block.

Returns

The carry flag must be clear.

Uses

Flags

See Also

Begin_PM_App


Init_Complete
include vmm.inc

mov     ebx, SysVM                  ; system VM handle

mov     esi, OFFSET32 CommandTail   ; points to WIN386 command tail

mov     eax, Init_Complete

VMMcall System_Control

The Init_Complete message notifies the virtual device that the system and virtual devices have initialized successfully. Virtual devices that use V86 memory typically search for available pages, in the range 0A0h through 100h, when processing this message.

Parameter	Description

SysVM	Specifies a handle identifying the system virtual machine.

CommandTail	Points to the command tail retrieved from the program segment prefix (PSP) of WIN386.EXE. The first byte in the command tail specifies the length in bytes of the tail.

Returns

The carry flag is clear if the virtual device successfully completes its initialization. Otherwise, the carry flag is set to prevent the system from loading the virtual device.

Comments

The system sends this message just before it releases its INIT pages and takes the instance snapshot.

Virtual devices can use the Simulate_Int and Exec_Int services to execute code in the system virtual machine.

Uses

Flags

See Also

Device_Init


Power_Event
include vmm.inc

include power.inc

mov     ebx, 0

mov     esi, Event              ; event notification message

mov     edi, OFFSET32 Return    ; points 4-byte return value

mov     eax, Power_Event

VMMcall System_Control

The Power_Event message notifies the virtual device that a power event has just occurred.

Parameter	Description

Event	Specifies the type of power event. This parameter can be one of the following values:

Value	Meaning

PWR_SUSPENDREQUEST	Suspend operation.

PWR_SUSPENDRESUME	Resume operation after suspension.

PWR_CRITICALRESUME	Resume critical operations after suspension.

Return	Points to the doubleword to receive the return value. The return value can be one of the following values:

Value	Meaning

PWR_OK	Virtual device processed the event successfully.

PWR_FAIL	Virtual device failed to process the event.

All other values are reserved.

Returns

The carry flag is clear and the doubleword pointed to by Return contains the return value.

Comments

The EBX register must be zero on entry. The EDX register is reserved; its value must be preserved.

Uses

Flags


Query_Destroy
include vmm.inc

mov     ebx, VM         ; VM handle

mov     eax, Query_Destroy

VMMcall System_Control

The Query_Destroy message directs the virtual device to display a warning message if the destruction of the specified virtual machine will disrupt the operation of the virtual device. The virtual shell device sends this message before attempting to destroy a virtual machine that has not terminated normally.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to destroy.

Returns

The carry flag is set if the destruction of the virtual machine will disrupt the virtual device. Otherwise, the carry flag is clear.

Comments

Virtual devices that set the carry flag must also display a message box, using the SHELL_Message service to inform the user of the potential problem. The user can then decide whether to continue destroying the virtual machine.

Uses

Flags

See Also

Destroy_VM, SHELL_Message


Reboot_Processor
include vmm.inc

mov     eax, Reboot_Processor

VMMcall System_Control

The Reboot_Processor message directs the virtual device to restart the computer. The system continues to call the virtual devices until one that can restart the computer (usually the virtual keyboard device) does so.

This message has no parameters.

Returns

The carry flag is clear.

Uses

Flags

See Also

Crit_Reboot_Notify


Set_Device_Focus
include vmm.inc

mov     ebx, VM         ; VM handle

mov     edx, VID        ; ID of virtual device to receive focus

mov     esi, Flags      ; flags for device-critical focus

mov     edi, AssocVM    ; handle of associated VM

mov     eax, Set_Device_Focus

VMMcall System_Control

The Set_Device_Focus message sets the focus of the specified virtual device to the specified virtual machine.

Parameter	Description

VM	Specifies a handle identifying the virtual machine.

VID	Specifies the identifier for the virtual device to receive the focus. If this parameter is zero, all virtual devices receive the focus.

Flags	Specifies how to set the focus if the VID parameter is zero. This parameter can have the following value:

Value	Meaning

1	Used by the virtual shell device to determine which virtual machine to set focus for. If this value is given, the AssocVM parameter may specify a virtual machine.

All other values are reserved.

AssocVM	Specifies a handle identifying a virtual machine associated with a problem. This parameter is zero if there is no such virtual machine. This parameter is used only if the Flags parameter is set to 1.

Returns

The carry flag must be clear.

Comments

A virtual device that receives the focus should take steps, such as disabling I/O trapping, to allow the virtual machine to run as fast as possible.

Uses

Flags


Sys_Critical_Exit
include vmm.inc

mov     eax, Sys_Critical_Exit

VMMcall System_Control

The Sys_Critical_Exit message notifies the virtual device that the system is exiting either normally or as a result of a crash. Virtual devices should reset their associated hardware to allow for a return to the state before Windows was started.

The system disables interrupts before sending this message.

This message has no parameters.

Returns

The carry flag must be clear.

Comments

The virtual device must not call the Simulate_Int or Exec_Int service.

Uses

Flags

See Also

Sys_Critical_Init, Sys_VM_Terminate


Sys_Critical_Init
include vmm.inc

mov     ebx, SysVM                  ; system VM handle

mov     esi, OFFSET32 CommandTail   ; points to WIN386 command tail

mov     eax, Sys_Critical_Init

VMMcall System_Control

The Sys_Critical_Init message notifies the virtual device that Windows is starting. The system sends this message to direct virtual devices to carry out, as quickly as possible, the minimum number of tasks needed to prepare the device for enabled interrupts. While virtual devices process this message, interrupts are disabled.

Parameter	Description

SysVM	Specifies a handle identifying the system virtual machine.

CommandTail	Points to the command tail retrieved from the program segment prefix (PSP) of WIN386.EXE. The first byte in the command tail specifies the length in bytes of the tail.

Returns

The carry flag is clear if the virtual device initialized successfully. Otherwise, the carry flag is set to prevent the system from loading the virtual device.

Comments

While processing this message, virtual devices typically initialize any critical functions needed to support interrupts and claim any V86 pages required to support the device. For example, the virtual display device claims the video memory. If a virtual device provides services, it should initialize any data associated with those services.

The virtual device must not use the Simulate_Int or Exec_Int services.

Uses

Flags

See Also

Device_Init, Sys_Critical_Exit


Sys_VM_Init
include vmm.inc

mov     ebx, SysVM      ; system VM handle

mov     eax, Sys_VM_Init

VMMcall System_Control

The Sys_VM_Init message directs the virtual device to initialize the state of the software in the system virtual machine. For example, the virtual display device issues an Interrupt 10h function to set the initial display mode.

Parameter	Description

SysVM	Specifies a handle identifying the system virtual machine.

Returns

The carry flag is clear if the virtual device initializes the system virtual machine successfully. Otherwise, the carry flag is set to direct Windows to exit immediately.

Uses

Flags

See Also

VM_Init


Sys_VM_Terminate
include vmm.inc

mov     ebx, SysVM              ; system VM handle

mov     eax, Sys_VM_Terminate

VMMcall System_Control

The Sys_VM_Terminate message notifies the virtual device that the system virtual machine is terminating. The system sends this message only after all other virtual machines have terminated, and only when the system is terminating normally.

Parameter	Description

SysVM	Specifies a handle identifying the system virtual machine.

Returns

The carry flag must be clear.

Comments

The virtual device can use the Simulate_Int and Exec_Int services in the system virtual machine.

Uses

Flags

See Also

VM_Terminate


System_Exit
include vmm.inc

mov     ebx, SysVM      ; system VM handle

mov     eax, System_Exit

VMMcall System_Control

The System_Exit message notifies the virtual device that the system is terminating either normally or as a result of a crash. Interrupts remain enabled while virtual devices process this message.

Parameter	Description

SysVM	Specifies a handle identifying the system virtual machine.

Returns

The carry flag must be clear.

Comments

The virtual device must not call the Simulate_Int or Exec_Int service, but the virtual device may modify the system virtual machine memory to restore the system state to allow Windows to exit without complication.

The system restores the instance snapshot before sending this message.

Uses

Flags

See Also

Sys_Critical_Exit


VM_Critical_Init
include vmm.inc

mov     ebx, VM                 ; new VM handle

mov     eax, VM_Critical_Init

VMMcall System_Control

The VM_Critical_Init message directs the virtual device to initialize itself for the new virtual machine. The system disables interrupts before sending this message.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to create.

Returns

The carry flag is clear if the virtual device initialized successfully. Otherwise, the carry flag is set to prevent the virtual machine from being created.

Comments

The virtual device must not use the Simulate_Int or Exec_Int services in the specified virtual machine.

Uses

Flags

See Also

Create_VM, VM_Init


VM_Init
include vmm.inc

mov     ebx, VM        ; new VM handle

mov     eax, VM_Init

VMMcall System_Control

The VM_Init message directs the virtual device to initialize the state of the software in the new virtual machine. For example, the virtual display device issues Interrupt 10h to set the initial display mode. The system enables interrupts before sending this message.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to create.

Returns

The carry flag is clear if the virtual device initialized the virtual machine successfully. Otherwise, the carry flag is set to prevent the system from creating the virtual machine.

Comments

The virtual device can use the Simulate_Int and Exec_Int services in the specified virtual machine.

Uses

Flags

See Also

Create_VM, VM_Critical_Init


VM_Not_Executeable
include vmm.inc

mov     ebx, VM         ; VM handle

mov     edx, Flags      ; flags

mov     eax, VM_Not_Executeable

VMMcall System_Control

The VM_Not_Executeable message notifies the virtual device that the virtual machine is no longer capable of executing. The system sends this message as the first phase of terminating the virtual machine.

Parameter	Description

VM	Specifies a handle identifying the virtual machine.

Flags	Specifies the reason the virtual machine is no longer executable. This parameter can be one of the following values:

Value	Meaning

VNE_Crashed	Virtual machine has crashed.

VNE_Nuked	Virtual machine was destroyed while active.

VNE_CreateFail	Some device failed Create_VM.

VNE_CrInitFail	Some device failed VM_Critical_Init.

VNE_InitFail	Some device failed VM_Init.

Returns

The carry flag must be clear.

Comments

When destroying a running virtual machine, the system sends this message first and never sends the VM_Terminate message.

The virtual device must not call the Simulate_Int or Exec_Int service in the specified virtual machine.

Uses

Flags

See Also

VM_Terminate


VM_Resume
include vmm.inc

mov     ebx, VM         ; VM handle

mov     eax, VM_Resume

VMMcall System_Control

The VM_Resume message notifies the virtual device that the virtual machine is resuming after having been suspended. The virtual device should lock any resources, and prepare internal data structures for the virtual machine to start running again.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to resume.

Returns

The carry flag is clear if the virtual device can support resumption of the virtual machine. Otherwise, the carry flag is set to prevent the system from resuming the virtual machine.

Comments

The system never sends the VM_Resume message without having first sent a VM_Suspend message.

Uses

Flags

See Also

VM_Suspend


VM_Suspend
include vmm.inc

mov     ebx, VM         ; VM handle

mov     eax, VM_Suspend

VMMcall System_Control

The VM_Suspend message notifies the virtual device that the system is suspending execution of the virtual machine. The virtual device should unlock any resources associated with the virtual machine.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to suspend.

Returns

The carry flag must be clear.

Comments

The virtual machine remains suspended until explicitly resumed. The system sends the VM_Suspend message each time the virtual machine is suspended. It sends a VM_Resume message when the virtual machine is resumed.

The CB_VM_Status field in the control block for the virtual machine specifies whether the virtual machine is suspended.

Uses

Flags

See Also

VM_Resume


VM_Terminate
include vmm.inc

mov     ebx, VM             ; VM handle

mov     eax, VM_Terminate

VMMcall System_Control

The VM_Terminate message notifies the virtual device that system is terminating the specified virtual machine. The system sends this message when a virtual machine terminates normally.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to terminate.

Returns

The carry flag must be clear.

Comments

The virtual machine can call the Simulate_Int and Exec_Int services in the specified virtual machine.

Uses

Flags

See Also

System_Exit, VM_Not_Executeable


Miscellaneous Services

Begin_Reentrant_Execution	Start reentrant execution

End_Reentrant_Execution	End reentrant execution

GetSetDetailedVMError	Gets and sets error information

Hook_Device_Service	Install a hook for a device service

Hook_Device_V86_API	Installs an V86-mode API callback

Hook_Device_PM_API	Installs an protected-mode API callback

Install_Exception_Handler	Installs an exception handler

Map_Flat	Converts an V86 or protected-mode address

Map_Lin_To_VM_Addr	Converts a linear address

MMGR_SetNULPageAddr	Sets physical address of system nul page

Remove_Exception_Handler	Removes an exception handler

Set_Delete_On_Exit_File	Adds file to list to delete on exit

Set_System_Exit_Code	Sets the Windows exit code value

System_Control	Sends a control message to all virtual devices


Begin_Reentrant_Execution
include vmm.inc

VMMcall Begin_Reentrant_Execution

mov     [Count], ecx        ; reentrancy count

The Begin_Reentrant_Execution service starts reentrant execution. Virtual devices use this service when hooking VMM faults (reentrant processor exceptions) so that they may call nonasynchronous VMM or virtual device services or execute a virtual machine.

Most virtual devices have no reason to use this service. Do not use this service to avoid scheduling events on hardware interrupts.

This service has no parameters.

Returns

The ECX register contains the old reentrancy count. This count must be passed to the End_Reentrant_Execution service.

Uses

ECX, Flags

See Also

End_Reentrant_Execution


End_Reentrant_Execution
include vmm.inc

mov     ecx, Count      ; reentrancy count

VMMcall End_Reentrant_Execution

The End_Reentrant_Execution service ends reentrant execution. Virtual devices use this service in conjunction with the Begin_Reentrant_Execution service. A virtual device that calls Begin_Reentrant_Execution must call this service before returning.

Parameter	Description

Count	Specifies the reentrancy count previously returned by the Begin_Reentrant_Execution service.

Returns

This service has no return value.

Uses

Flags

See Also

Begin_Reentrant_Execution


GetSetDetailedVMError
include vmm.inc

mov     ebx, VM       ; VM Handle or 0 if Create_VM error

mov     ecx, GetSet   ; zero if get, nonzero zero if set

mov     eax, Error    ; error code if ecx nonzero

mov     edx, RefData  ; points to reference data if ecx nonzero

VMMcall GetSetDetailedVMError

jz      no_error_info   ; zero set if no error information

mov     [Error], eax    ; error code

mov     [RefData], edx  ; reference data for the error code

The GetSetDetailedVMError service sets detailed error code for a virtual machine crash or start-up error.

This service is only available for Windows 3.1 or later.

Parameter	Description

VM	Specifies a handle identifying the virtual machine. If this parameter is zero, the service gets or sets error information for the Create_VM message.

GetSet	Specifies which action tot take. If zero, the service retrieves error information. If nonzero, the service sets error information.

Error	Specifies the error code to set. This parameter is used only if GetSet is nonzero. There are the following error code values:

Value	Meaning

GSDVME_CrtNoMsg	Supress standard messages; the SHELL_Message service is used for custom messages.

GSDVME_DevNuke	Device-specific problem.

GSDVME_DevNukeHdwr	Device-specific problem caused by software running in the virtual machine.

GSDVME_InsMemEMS	Available EMS memory is less than requested; set by the virtual V86 mode memory manager.

GSDVME_InsMemV86	Insufficient V86 memory; set by the virtual V86 mode memory manager.

GSDVME_InsMemV86Hi	Insufficient high MS-DOS memory; set by the virtual MS-DOS manager.

GSDVME_InsMemVid	Insufficient base video memory; set by the virtual display device.

GSDVME_InsMemVM	Insufficient base virtual machine memory for control block or instance buffer.

GSDVME_InsMemXMS	Available XMS memory is less than requested; set by the virtual V86 mode memory manager.

GSDVME_InsV86Space	Available V86 address space is less than requested; set by the virtual V86 mode memory manager.

GSDVME_InvalFlt	Invalid fault.

GSDVME_InvalGpFlt	Invalid GP fault.

GSDVME_InvalInst	Attempt to execute an invalid instruction.

GSDVME_InvalPgFlt	Invalid page fault.

GSDVME_InsMemDev	Could not allocate base virtual machine memory for device.

GSDVME_NukeNoMsg	Suppress standard messages; the SHELL_Message service is used for custom messages.

GSDVME_OkNukeMask	Reserved for the exclusive use of the virtual MS-DOS manager.

GSDVME_PrivInst	Attempt to execute a privledged instruction.

GSDVME_UserNuke	User requested running virtual machine be terminated.

Error values that have the high word set to 2 are intended to be used when a virtual machine fails on start up.

RefData	Points to reference data to set. The reference data is an additional doubleword of data associated with an error. This parameter is used only if GetSet is nonzero. This parameter is zero if there is no associated reference data.

Returns

If the zero flag is clear, the EAX register contains the error code and the EDX register contains the address of the reference data associated with the error code. The zero flag is set if the service found no detailed error information.

Comments

Uses

EAX, EDX, Flags


Hook_Device_Service
include vmm.inc

mov     eax, Service            ; specifies the service to hook

mov     esi, OFFSET32 HookProc  ; points to the hook procedure to install

VMMcall Hook_Device_Service

jc      not_installed           ; carry set if error

mov     [Real_Proc], esi

The Hook_Device_Service service allows one virtual device to monitor or replace the services of another virtual device or of the VMM itself.

Parameter	Description

Service	Specifies the virtual device or VMM service to hook.

HookProc	Points to the hook procedure to install. The hook procedure is called with the same parameters as the service specified by the Service parameter.

Returns

The carry flag is clear and the ESI register contains the address of the service specifed by the Service parameter if this service is successful. Otherwise, the carry flag is set to indicate an error.

Comments

Virtual devices that use this service must use extreme care to preserve the full functionality of the virtual device whose services are monitored or replaced.

More than one virtual device can hook a device service. The last hook installed is the first one called.

The hook procedure must save and restore registers that are not modified by the hooked service. Also, if flags are a passed as an entry or exit parameter, the hook procedure must also preserve the flags.

If the hooked service uses the C calling convention, the hook procedure must copy the entire parameter stack frame before attempting to call the hooked service.

Uses

ESI, Flags


Hook_Device_V86_API
include vmm.inc

mov     eax, ID                 ; device ID

mov     esi, OFFSET32 Callback  ; points to new API callback

VMMcall Hook_Device_V86_API

The Hook_Device_V86_API service installs an API callback procedure allowing a virtual device to intercept calls to the V86 mode API of another virtual device. This service is intended to support virtual devices that need to monitor calls to the APIs of other virtual devices. Most virtual devices will never need this service.

Parameter	Description

ID	Specifies the identifier for the virtual device to monitor.

Handler	Points to the callback proecdure to install. See the Comments section for more information about the procedure.

Returns

The carry flag is clear and the ESI register contains the address of the previous callback procedure if the service is successful. Otherwise, the carry flag is set to indicate the specified virtual device does not support an API.

Comments

The system calls the callback procedure whenever an application in a virtual machine calls the API for the specified virtual machine. The system calls the callback as follows:

mov     ebx, VM             ; current VM handle

mov     ebp, OFFSET32 crs   ; points to Client_Reg_Struc

call    [Callback]

The VM parameter is a handle identifying the current virtual machine and crs points to a Client_Reg_Struc structure containing the regsiter values of the current virtual machine. Other registers contain the parameter values intended for the API.

The callback procedure can carry out tasks but eventually must pass execution to the previous API callback procedure, preserving the EBX and EBP registers when it calls.

Uses

ESI, Flags

See Also

Hook_Device_PM_API


Hook_Device_PM_API
include vmm.inc

mov     eax, ID                 ; device ID

mov     esi, OFFSET32 Callback  ; points to new API callback

VMMcall Hook_Device_PM_API

The Hook_Device_PM_API service installs an API callback procedure allowing a virtual device to intercept calls to the protected-mode API of another virtual device. This service is intended to support virtual devices that need to monitor calls to the APIs of other virtual devices. Most virtual devices will never need this service.

Parameter	Description

ID	Specifies the identifier for the virtual device to monitor.

Handler	Points to the callback proecdure to install. See the Comments section for more information about the procedure.

Returns

The carry flag is clear and the ESI register contains the address of the previous callback procedure if the service is successful. Otherwise, the carry flag is set to indicate the specified virtual device does not support an API.

Comments

The system calls the callback procedure whenever an application in a virtual machine calls the API for the specified virtual machine. The system calls the callback as follows:

mov     ebx, VM             ; current VM handle

mov     ebp, OFFSET32 crs   ; points to Client_Reg_Struc

call    [Callback]

The VM parameter is a handle identifying the current virtual machine and crs points to a Client_Reg_Struc structure containing the regsiter values of the current virtual machine. Other registers contain the parameter values intended for the API.

The callback procedure can carry out tasks but eventually must pass execution to the previous API callback procedure, preserving the EBX and EBP registers when it calls.

Uses

ESI, Flags

See Also

Hook_Device_V86_API


Install_Exception_Handler
include vmm.inc

mov     esi, Exception          ; points to an Exception_Handler_Struc

VMMcall Install_Exception_Handler

jc      not_installed           ; carry set if error

The Install_Exception_Handler service installs a ring-0 exception handler.

Parameter	Description

Exception	Points to an Exception_Handler_Struc structure containing information about the exception handler to install.

Returns

The carry flag is clear if the service is successful. Otherwise, the carry flag is set to indicate an error

Comments

The system calls the exception handler only if the exception occurs within the range of address specified by the EH_StartIP and EH_EndIP fields in the Exception_Handler_Struc structure. The system calls the exception handler with the stack and all registers in same state as when exception occurred.

Uses

Flags

See Also

Remove_Exception_Handler


Map_Flat
include vmm.inc

mov     ah, SegOffset    ; offset in Client_Reg_Struc to segment reg

mov     al, OffOffset    ; offset in Client_Reg_Struc to offset reg

VMMcall Map_Flat

cmp     eax, -1         ; -1 if error

je      error

mov     [LinAddr], eax  ; ring-0 linear address

The Map_Flat service converts a segment:offset or selector:offset pair into a linear address. This service works only for the current virtual machine. It determines whether the value passed to it is a V86 segment or a protected-mode selector by the execution mode of the current virtual machine.

Parameter	Description

SegOffset	Specifies the offset in bytes from the start of the Client_Reg_Struc structure to the segment register that contains the segment address or selector to convert.

OffOffset	Specifies the offset in bytes from the start of the Client_Reg_Struc structure to the register that contains the address offset to convert. If this parameter is -1, this service uses 0 as the address offset to convert.

Returns

The EAX register contains the ring-0 linear address that corresponds to the specified V86 or protected-mode address. The EAX register contains -1 if if the specified selector is invalid.

Comments

Before converting an address, Map_Flat checks the current execution mode and, for protected-mode applications, the segment granularity (16- or 32-bit offsets). If the virtual machine is running a 32-bit protected mode application, it uses 32-bit address offsets. For V86 and 16-bit protected-mode applications, it uses 16-bit address offsets and ignores the high word if the OffOffset parameter specifies a 32-bit register.

Example

The following example converts the address Client_DS:Client_DX and returns the linear address in EAX:

mov     ax, (Client_DS SHL 8) + Client_DX

VMMcall Map_Flat

Uses

EAX, Flags

See Also

Client_Ptr_Flat


Map_Lin_To_VM_Addr
include vmm.inc

mov     eax, LineAddr   ; Linear address to convert

mov     ecx, Limit      ; segment limit in bytes

VMMcall Map_Lin_To_VM_Addr

jc      error           ; carry set if error

mov     [SegSel], cx    ; segment or selector

mov     [Offset], edx   ; address offset

The Map_Lin_To_VM_Addr service converts a 32-bit ring-0 linear address into an V86 or protected-mode address. This service converts the address for use with the current execution mode of the current virtual machine.

Parameter	Description

LinAddr	Specifies the linear address to convert.

Limit	Specifies the zero-based segment limit (0 specifies a one-byte segment, 1 is a two-byte segment, and so on). This parameter is used only if the service creates an LDT selector.

Returns

If the carry flag is clear, the CX register contains the segment address or selector, and EDX regsiter contains the address offset. This offset is always zero if the virtual machine is running a protected mode application.

The carry flag is set to indicate an error such as no LDT selectors available.

Comments

If the virtual machine is running in V86 mode, the LineAddr parameter must specify a linear address that is within the 1 megabyte V86 address space of the current virtual machine. The service returns a segment:offset pair.

If the virtual machine is running a protected-mode application, the service returns a selector:offset pair. This service creates a new selector in the current virtual machine's LDT if the specified base and limit values do not match a selector the service previously allocated.

A virtual device must never free a selector that is returned by this service. For this reason, this service should be used sparingly.

Uses

ECX, EDX, Flags

See Also

Map_Flat


MMGR_SetNULPageAddr
include vmm.inc

mov     eax, PhysAddr       ; physical address for system nul page

VMMcall MMGR_SetNULPageAddr

The MMGR_SetNULPageAddr service sets the physical address of the system nul page.

This service is for the exclusive use of the virtual V86MMGR device. The virtual device calls this service, while processing the Init_Complete message, to set the address of a known nonexistent page in the system.

Parameter	Description

PhysAddr	Specifies the physical address of the system nul page. This parameter is the page number for the nul page shifted left by 12 bits.

Returns

This service has no return value.

Uses

Flags

See Also

_GetNULPageHandle


Remove_Exception_Handler
include vmm.inc

mov     esi, Exception          ; points to an Exception_Handler_Struc

VMMcall Remove_Exception_Handler

jc      not_removed             ; carry set if error

The Remove_Exception_Handler service removes the specified exception handler.

Parameter	Description

Exception	Points to an exception handler structure containing information about the exception handler to remove. This exception handler must have been previously installed using the Install_Exception_Handler service.

Returns

The carry flag is clear if the service is successful. Otherwise, the carry flag is set to indicate an error such as an invalid exception handler address.

Uses

Flags

See Also

Install_Exception_Handler, Exception_Handler_Struc


Set_Delete_On_Exit_File
include vmm.inc

mov     esi, Filename       ; points to filename to add

VMMcall Set_Delete_On_Exit_File

jc      not_added           ; carry set on error

The Set_Delete_On_Exit_File service adds the specified filename to the list of files to delete when Windows terminates.

This service is for the exclusive use of the virtual pagefile device; other virtual devices must not use this service.

Parameter	Description

Filename	Specifies a null-terminated string identifying the file to delete. The string must specify a drive letter and full path.

Returns

The carry flag is clear if the service adds the file to the list. Otherwise, the carry flag is set.

Uses

All registers except EBX, EBP, and the segment registers.


Set_System_Exit_Code
include vmm.inc

mov     al, ExitCode        ; exit code to set

VMMcall Set_System_Exit_Code

The Set_System_Exit_Code service sets the exit code value that Windows returns to MS-DOS when Windows terminates. The system copies this value to the AL register when it executes the MS-DOS End Program function (Interrupt 21h Function 4Ch).

This service is intended for the exclusive use of the virtual shell device.

Parameter	Description

ExitCode	Specifies the exit code value.

Returns

This service has no return value.

Comments

This exit code is associated only with the exit of the system not the system virtual machine.

In the case of an abnormal termination the system may set its own exit code value and ignore the value set by this service.

Uses

EDX, Flags


System_Control
include vmm.inc

mov     eax, Message    ; system control message

mov     ebx, VM         ; VM handle (if needed by message)

mov     esi, Param1     ; message-specific parameter

mov     edi, Param2     ; message-specific parameter

mov     edx, Param3     ; message-specific parameter

VMMcall System_Control

jc      error           ; carry set if error

The System_Control service sends system control messages to all the virtual devices and, depending on the message, to the VMM.

Parameter	Description

Message	Specifies the system control message. This parameter can be one of the following values:

Value	Meaning

Begin_PM_App	A protected-mode application is starting

Close_VM_Notify	A virtual machine is closing

Create_VM	A virtual machine is being created

Critical_Reboot_Notify	System is rebooting (interrupt disabled)

Debug_Query	Requests for virtual device's debugging interface

Destroy_VM	A virtual machine is being destroyed

Device_Init	Virtual devices initializing (interrupts enabled)

Device_Reboot_Notify	System is rebooting (interrupts enabled)

End_PM_App	A protected-mode application is ending

Init_Complete	All virtual devices have initialized

Power_Event	Power is being suspended or resumed

Reboot_Processor	Virtual device must reboot system if it can

Set_Device_Focus	A virtual device is taking the focus

Sys_Critical_Exit	System is terminating (interrupt disabled)

Sys_Critical_Init	Virtual devices initializing (interrupts disabled)

Sys_VM_Init	System VM is being created

Sys_VM_Terminate	System VM is being destroyed

System_Exit	System is terminating (interrupts enabled)

VM_Critical_Init	Virtual machine being created (interrupts disabled)

VM_Init	Virtual machine being created (interrupts enabled)

VM_Not_Executeable	Virtual machine being destroyed

VM_Resume	Virtual machine execution resumed

VM_Suspend	Virtual machine execution suspended

VM_Terminate	Virtual machine begin destroyed

For more information about these messages, see the individual message descriptions.

VM	Specifies a handle identifying a virtual machine. This parameter is not required by every system control message.

Param1	Specifies a message-specific parameter.

Param2	Specifies a message-specific parameter.

Param3	Specifies a message-specific parameter.

Returns

The carry flag is clear if the service is successful. Otherwise, the carry flag is set to indicate an error.

If the Create_VM message is successful, the EBX register contains the new virtual machine handle.

Comments

Although virtual devices may receive many of the system control messages, they may send only the following messages:

Message	Restructions

Create_VM	May only be sent by the virtual shell device.

Destroy_VM	May only be sent by the virtual shell device.

Set_Device_Focus	May be sent by any virtual device. If the device ID is zero, all devices with settable focus must set their focus to the specified virtual machine.

End_PM_App	May only be sent by the virtual MS-DOS manager.

Virtual devices must send and reply to messages correctly to prevent erratic system behavior.

This service uses the ECX register, therefore the register cannot be used to pass data through to the virtual device receiving the control message.

Uses

Flags, EBX if Create_VM


VMM Memory Management Services

Device V86 Page Management

Free Physical Memory Management

GDT/LDT Management

Heap Allocation

Memory Management for Protected-Mode

Miscellaneous Memory Management

Page Allocation and Management

System-Internal Memory Management

V86 Address Space Mapping and Allocation


Device V86 Page Management

_Assign_Device_V86_Pages	Assigns V86 pages to a virtual device

_DeAssign_Device_V86_Pages	Unassigns V86 pages

_Get_Device_V86_Pages_Array	Retrieves assignment arrays

Hook_V86_Page	Installs a page-fault callback procedure


Free Physical Memory Management

_AddFreePhysPage	Adds free physical pages

_MapFreePhysReg	Maps pages into a free physical region

_PageResetHandlePAddr	Adds physical pages to a memory block

_SetFreePhysRegCalBk	Installs a free-physical-region callback

_UnmapFreePhysReg	Unmaps pages in a free physical region

_XchgFreePhysReg	Exchanges a physical address


GDT/LDT Management

_Allocate_GDT_Selector	Allocates a GDT selector

_Allocate_LDT_Selector	Allocates a selector

_BuildDescriptorDWORDs	Builds a selector descriptor

_Free_GDT_Selector	Frees a GDT selector

_Free_LDT_Selector	Frees an LDT selector

_GetDescriptor	Retrieves a copy of a descriptor

_SetDescriptor	Sets the descriptor for a selector


Heap Allocation

_HeapAllocate	Allocates memory from the heap

_HeapFree	Frees a memory block from the heap

_HeapGetSize	Returns the size of a heap memory block

_HeapReAllocate	Reallocates a heap memory block


Memory Management for Protected-Mode

_GetV86PageableArray	Returns pageable array

_LinMapIntoV86	Maps pages into V86 addresses

_LinPageLock	Locks pages

_LinPageUnLock	Unlocks pages

_PageCheckLinRange	Checks range of linear addresses

_PageDiscardPages	Discards pages

_SelectorMapFlat	Returns the base address of the selector

_SetResetV86Pageable	Modifies locking and unlocking


Miscellaneous Memory Management

_AddInstanceItem	Add an instance item

_Allocate_Device_CB_Area	Allocates a control block area

_MapPhysToLinear	Returns the linear address of physical memory


Page Allocation and Management

_CopyPageTable	Copies page table entries

_GetAppFlatDSAlias	Returns read-only selector for flat DS

_GetDemandPageInfo	Retrieves information for demand paging

_GetFirstV86Page	Returns number of first page for V86 memory

_GetFreePageCount	Returns the number of free pages

_GetGlblRng0V86IntBase	Returns address for ring-0 V86 handlers

_GetLastV86Page	Returns number of last page of V86 memory

_GetNulPageHandle	Returns handle of system nul page

_GetSysPageCount	Returns count of system pages

_GetVMPgCount	Returns count of pages in a virtual machine

_ModifyPageBits	Modifies page attribute bits

_PageAllocate	Allocates a memory block

_PageFree	Frees a memory block

_PageGetAllocInfo	Returns allocation information

_PageGetSizeAddr	Returns size and address of memory block

_PageLock	Locks pages

_PageReAllocate	Reallocates a block of memory

_PageUnLock	Unlocks pages


System-Internal Memory Management

_GetSetPageOutCount	Sets or returns the page out count

_MMGR_Toggle_HMA	Enables or disables the HMA

_PageOutDirtyPages	Flushes dirty pages

_SetLastV86Page	Sets last page in V86 address space

Set_Physical_HMA_Alias	Sets the physical HMA alias


V86 Address Space Mapping and Allocation

_Add_Global_V86_Data_Area	Adds a region to global V86 data

_Allocate_Global_V86_Data_Area	Allocates a global V86 data area

_Allocate_Temp_V86_Data_Area	Allocates a V86 memory block

_Free_Temp_V86_Data_Area	Frees a V86 memory block

_MapIntoV86	Maps pages into V86 address

_PhysIntoV86	Maps physical pages into V86 memory

_TestGlobalV86Mem	Tests for global V86 memory


_Assign_Device_V86_Pages
include vmm.inc

VMMcall _Assign_Device_V86_Pages, <VMLinrPage, nPages, VM, flags>

or      eax, eax            ; nonzero if assigned, zero if error

jz      not_assigned

The _Assign_Device_V86_Pages service assigns to a virtual device one or more pages of the V86 address space.

Parameter	Description

VMLinrPage	Specifies the linear page number of the first page of V86 address space to assign. The page number must be in the range 0 through 10Fh.

nPages	Specifies the number of pages to assign. All pages to assign must be within the V86 address space. If any a page is already assigned, this service returns an error value.

VM	Specifies a handle identifying a virtual machine. If this parameter is a valid handle, the assignments apply only to the specified virtual machine. If this parameter is zero, the assignments apply to all virtual machines.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error such as a specified page already assigned or an invalid page range.

Comments

A virtual device can make global assignments at any time, including during device initialization. For global assignments, the VM parameter must be zero. The virtual device must not attempt to assign a page that is already assigned. A virtual device can make local assignments only after device initialization is complete.

Uses

EAX

See Also

_DeAssign_Device_V86_Pages


_DeAssign_Device_V86_Pages
include vmm.inc

VMMcall _DeAssign_Device_V86_Pages, <VMLinrPage, nPages, VM, flags>

or      eax, eax        ; nonzero if unassigned, zero if error

jz      not_unassigned

The _DeAssign_Device_V86_Pages service unassigns a region in the V86 address space which was previously assigned using the _Assign_Device_V86_Pages service.

Parameter	Description

VMLinrPage	Specifies the linear page number of the first page to unassign. The page number must be in the range 0 through 10Fh.

nPages	Specifies the number of pages to unassign. All pages to unassign must be within the V86 address space. If any a page is not assigned, this service returns an error value.

VM	Specifies a handle identifying a virtual machine. If this parameter is a valid handle, the service unassigns pages previously assigned to the virtual machine. If this parameter is zero, the service unassigns pages that were previously assigned to all virtual machines.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service was successful. Otherwise, EAX contains zero to indicate an error such as a page in the range already unassigned or an invalid page range.

Comments

This service only works after device initialization is complete.

A virtual device must not attempt to unassign pages that have not yet been assigned, or attempt to globally unassign pages that were only locally assigned.

Uses

EAX

See Also

_Assign_Device_V86_Pages


_Get_Device_V86_Pages_Array
include vmm.inc

VMMcall _Get_Device_V86_Pages_Array, <VM, <OFFSET32 ArrayBuf>, flags>

or      eax, eax        ; nonzero if retrieved, zero if error

jz      not_retrieved

The _Get_Device_V86_Pages_Array service retrieves a copy of the assignment array used by the _Assign_Device_V86_Pages and _DeAssign_Device_V86_Pages services. Virtual devices use the assignment array to determine which regions of the V86 address space are currently assigned, and which are available.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to retrieve the assignment array for. If this parameter is zero, the service retrieves the global assignment array.

ArrayBuf	Points to the 36-byte buffer that receives the assignment array.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, it contains zero to indicate an error such as an invalid virtual machine handle.

Comments

The assignment array consists of 110h bits with each bit representing a single page in the V86 address space. If a bit is 1, the corresponding page is assigned. If a bit is 0, the corresponding page is not assigned.

The global assignment array does not indicate which pages are available. A page is available for global assignment only if it is neither globally nor locally assigned. To determine whether a page is available for global assignment, a virtual device must check the global assignment array, and then check the assignment arrays for each virtual machine.

Uses

EAX

See Also

_Assign_Device_V86_Pages, _DeAssign_Device_V86_Pages


Hook_V86_Page
include vmm.inc

mov     eax, PageNum            ; page number

mov     esi, OFFSET32 Callback  ; points to Address of trap routine

VMMcall Hook_V86_Page

The Hook_V86_Page service install a callback procedure to handle faults for the specified page. Virtual devices, such as the virtual display device, use this service to detect when particular address ranges are accessed.

Parameter	Description

Page	Specifies the number of the V86 page to install the callback procedure for. This number must be within the range specified by the number of the last V86 page and 0FFh.

Callback	Points to the callback procedure to install. See the Comments section for more information about this procedure.

Returns

The carry flag is clear if the service installs the callback procedure. Otherwise, the carry flag is set to indicate an error such as an invalid page number or the page is already hooked.

Comments

The system calls the callback procedure whenever a page fault occurs for the specified page regardless of the current virtual machine.

The system calls the callback as follows:

mov     eax, Page     ; faulting page number

mov     ebx, VM       ; current VM handle

call    [Callback]

The Page parameter specifies the number of the page that caused the page fault and VM is the handle of the current virtual machine. The EBP register does not point to a client register structure.

The callback procedure must either map physical memory into page causing the page fault or terminate the virtual machine. In unusual circumstances, the virtual device may need to map the system nul page into the faulting page.

Virtual devices must not rely on the contents of the CR2 (page fault) register. Instead, the callback procedure must use the Page parameter to determine which page caused the fault.

Uses

Flags


_AddFreePhysPage
include vmm.inc

VMMcall _AddFreePhysPage, <PhysPgNum, nPages, flags>

mov     [PagesAdded], eax       ; 0 = none, 1 = some, 2 = all

The _AddFreePhysPage service adds one or more physical pages to the free memory pool. Virtual devices use this service to add pages that the Windows loader could not find, but that the virtual device did find. For example, the V86MMGR device adds any unused physical pages it finds when using the Global EMM Import function of a 386 LIMulator.

This service is only available during initialization and only in Windows version 3.1 and later.

Parameter	Description

PhysPgNum	Specifies the physical page number of the first page to add. The page number must be greater than or equal to 110h; only extended memory pages may be added to the pool. The specified pages must be read/write physical memory pages, and must be available for use at any time.

nPages	Specifies the number of physical pages to add.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains one of the following values:

Value	Meaning

0	None of the specified physical pages were added to the free pool.

1	Some, but not all, of the specified physical pages were added.

2	All of the specified physical pages were added.

Comments

A virtual device must not attempt to use pages once it has added them to the free pool, or attempt to add pages that are already available to the system.

This service returns an error if the number of pages to add exceeds the limit of the internal data structure the system uses the manage the free pool. The internal data structure is allocated during initialization and cannot be modified.

Uses

EAX

See Also

_GetFreePageCount


_MapFreePhysReg
include vmm.inc

VMMcall _MapFreePhysReg, <LinPgNum, nPages, flags>

or      eax,eax         ; nonzero if mapped, zero if error

je      not_mapped

The _MapFreePhysReg service maps one or more physical pages into a free physical region. The service maps physical pages currently in the free list to the specified pages in the region.

Parameter	Description

LinPgNum	Specifies the linear page number of the first page to map. The page must be in a free physical region previously created using the _PageAllocate service. A linear page number is a linear address shifted right by 12 bits right.

nPages	Specifies number of pages to map. All pages must be within the free physical region.

flags	Specifies the operation flags. This parameter can be the following value:

Value	Meaning

PageFixed	Maps the specified pages as fixed pages, permanently locking the pages at the specified address. If this value is not given, the pages are not fixed. Virtual devices never return fixed pages to the system.

All other values are reserved.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains returns zero specifying an invalid linear page number, an invalid range of pages, part of the page range already present, insufficient number of pages on free list, or an invalid use of the PageFixed value.

Comments

This service is intended to be used in a free-physical-region callback procedure installed using the _SetFreePhysRegCalBk service. Virtual devices should not call this service until after the Sys_VM_Init message or the Init_Complete message has been received.

The PageFixed value allows a virtual device to maintain a cache of memory which has a minimum size. The virtual device maps a predetermined number of pages using the PageFixed value to ensure that this cache has its minimum size. The virtual device never unmaps these pages. The virtual device maps any additional pages without using the PageFixed value. This allows these pages to be unmapped later. Occasionally, there may be too few physical pages to attain the minimum cache size. The virtual device must be prepared to handle this condition.

Uses

EAX

See Also

_SetFreePhysRegCalBk, _UnmapFreePhysReg


_PageResetHandlePAddr
include vmm.inc

VMMcall _PageResetHandlePAddr, <hMem, PgOff, nPages, PhysPgNum, flags>

or      eax, eax                ; nonzero if substituted, zero if error

jz      not_substituted

The _PageResetHandlePAddr service substitutes one or more pages in a memory block with physical pages not previously available to the system. This service is similar to the _AddFreePhysPage service, but allows memory to be used in a slightly different way.

This service is only available for Windows version 3.1 and later.

Parameter	Description

hMem	Specifies a handle identifying a memory block. This handle must have been previously created using the _PageAllocate or _PageReAllocate service.

PgOff	Specifies the offset in pages from the start of the memory block to the first page to be substituted.

nPages	Specifies the number of pages to substitute.

PhysPgNum	Specifies the number of the first physical page to substitute into the memory block. The page number must be greater than or equal to 110h; only extended memory pages may be added to the block. The specified pages must be read/write physical memory pages, and must be available for use at any time.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero if the service is successful. Otherwise, EAX contains zero to indicate an error, such as an invalid memory handle, an invalid range of pages, or an invalid physical page number.

Comments

This service returns an error if the sum of the PgOff and nPages is greater than the size of the memory block.

A virtual device must not attempt to use pages once it has added them to the free pool, or attempt to add pages that are already available to the system.

This service returns an error if the number of pages to add exceeds the limit of the internal data structure the system uses the manage the free pool. The internal data structure is allocated during initialization and cannot be modified.

This service converts pages that are substituted into the block to fixed pages. These pages are always locked, and cannot be unlocked.

This service maps a new physical page in at the specified locations and puts the existing physical memory in the free list. The contents of the freed pages are not preserved.

Uses

EAX

See Also

_AddFreePhysPage


_SetFreePhysRegCalBk
include vmm.inc

VMMcall _SetFreePhysRegCalBk, <Callback, flags>

or      eax, eax            ; nonzero if installed, zero if error

jz      not_installed

The _SetFreePhysRegCalBk service installs a callback procedure for managing the free list for a free physical region. The system calls the callback procedure whenever the memory manager puts a page on the free list or wants to obtain a physical page.

Any number of callback procedures can be installed.

This service is only available during initialization.

Parameter	Description

Callback	Points to the callback procedure to install. See the Comments section for more information about this procedure.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error such as insufficient memory to define the callback procedure.

Comments

When the system places a page on the free list, the system gives a callback procedure the option to take the page and map it in a free physical region using the _MapFreePhysReg service. When the system needs a page, the system requests pages from the callback procedures. They provide pages by using the _UnmapFreePhysReg service to unmap the pages from the free physical region and put it back on the free list.

The system calls the callback procedure as follows:

mov     eax, Request    ; 0 for pages available, 1 for pages needed

mov     ecx, Pages      ; count of pages available or needed

call    [Callback]

jc      dont_chain      ; carry set if request satisfied

The Request parameter specifies whether the call is a notification of free pages or a request for free pages. This parameter is 0 if the pages are available and 1 if the pages are needed. All other values are reserved.

The Pages parameter specifies the count of page either currently available in the free list, or requested by the memory manager to be placed on the free list.

The callback procedure sets the carry flag to indicate that it carried out the request, and to prevent the system from calling the next callback procedure in the chain. If the callback procedure cannot complete the entire request, it must clear the carry flag.

The callback procedure can modify all registers except the segment registers and EBP.

If more than one callback procedure is installed, the system calls each procedure in the chain unless a procedure returns with the carry flag set. The system varies the order in which it calls the procedures, ensuring that every procedure is periodically the first to be called.

When Request is 1, the callback procedure must release pages for regions which were mapped without the PageFixed value.

The callback procedure must release all free physical region pages which were mapped without the PageFixed value.

The callback procedure can release more pages than requested. The extra pages remain on the free list until the next operation places pages on the free list. At this point, the system sends a notification (Request is 0) to the callback procedure for all of the pages currently on the free list.

In general, a callback procedure should not call any services other than the _MapFreePhysReg and _UnmapFreePhysReg services. Calling other services, particularly nonasynchronous services, may cause the system to be re-entered.

The system does not begin calling the free-physical-region callback procedures until after the Init_Complete message has been processed by all virtual devices.

Uses

EAX

See Also

_MapFreePhysReg, _PageAllocate


_UnmapFreePhysReg
include vmm.inc

VMMcall _UnmapFreePhysReg, <LinPgNum, nPages, flags>

or      eax, eax            ; nonzero if unmapped, zero if error

jz      not_unmapped

The _UnmapFreePhysReg service unmaps a page in a free physical region and places the physical memory back on the free list.

Parameter	Description

LinPgNum	Specifies the linear page number of the first page to unmap. A linear page number is a linear address shifted right by 12 bits.

nPages	Specifies the number of pages in the region to unmap. This region must lie within the boundaries of a free physical region previously allocated using the _PageAllocate service.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error, such as an invalid linear page number, an invalid range of pages, or part of the range already not present.

Comments

This service is intended to be used in a free-physical-region callback procedure installed using the _SetFreePhysRegCalBk service. Virtual devices should not call this service until after the Sys_VM_Init message or the Init_Complete message has been received.

If a virtual device maps pages using the PageFixed value with the _MapFreePhysReg service, it must not attempt to unmap the pages using the _UnmapFreePhysReg service.

Uses

EAX

See Also

_MapFreePhysReg, _PageAllocate


_XchgFreePhysReg
include vmm.inc

VMMcall _XchgFreePhysReg, <LinPgNum, PhysAddr, flags>

cmp     eax, 0FFFFFFFFh         ; 0FFFFFFFFh if error

je      not_exchanged

mov     [PageTable], eax        ; previous page table entry

The _XchgFreePhysReg service replaces the current physical address in a page table entry with a new physical address. A virtual device typically uses this service to compact a free physical region by assigning pages that are present to adjacent linear addresses (that is, by removing not-present pages from between present pages).

This is an asynchronous service.

Parameter	Description

LinPgNum	Specifies the linear page number of the first page in the region to exchange. A linear page number is a linear address shifted right by 12 bits. The specified page must be within a free physical region previously allocated using the _PageAllocate service.

PhysAddr	Specifies the physical address to insert into the page table entry specified by LinPgNum. This parameter must be a 32-bit physical address. If this parameter is zero, the service makes the page not present.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains the previous physical address for the specified page if the service is successful. If the specified page is not present, EAX contains zero. Otherwise, EAX contains 0FFFFFFFFh to indicate an error, such as an invalid linear page number.

Comments

A virtual device typically makes a series of calls to _XchgFreePhysReg, using the physical address return by one call as the parameter in the next call. To start the series, the virtual device sets the PhysAddr parameter to zero, and specifies a page known to be present. This forces the present page to be not present. The virtual device continues calling the service, specifying different page numbers, until the service returns 0.

This service cannot be used to change the number of pages which were mapped using the PageFixed value with the _MapFreePhysReg service.

The virtual pageswap device uses this service to read ahead and write behind without having to copy data. Using the _XchgFreePhysReg service in this way is restricted to the virtual pageswap device.

Failure to use this service properly can result in invalid page faults and loss of pages.

Uses

EAX

See Also

_MapFreePhysReg, _PageAllocate


_Allocate_GDT_Selector
include vmm.inc

VMMcall _Allocate_GDT_Selector, <DescDWORD1, DescDWORD2, flags>

mov     ecx, eax                    ; zero in eax and edx if error

or      ecx, edx

jz      error

mov     [Selector], eax             ; new selector

mov     word ptr [GDTSel], dx       ; selector for the GDT

ror     edx, 10h

mov     word ptr [SelCount], dx     ; number of selectors in GDT

The _Allocate_GDT_Selector service creates a new selector and adds it to the Global Descriptor Table (GDT).

Parameter	Description

DescDWORD1	Specifies the high doubleword of the descriptor for the selector. This parameter contains the high 16 bits of the base address, the high 4 bits of the limit, and the status and type bits.

DescDWORD2	Specifies the low doubleword of the descriptor for the selector. This parameter contains the low 16 bits of the base address and limit.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

If the service is successful, the EAX and EDX registers contain the following values:

Register	Description

EAX	Contains the new selector.

EDX	Contains the selector for and the size of the global descriptor table (GDT). The low 16 bits contains the selector for the GDT, and the high 16 bits contains the size of the GDT expressed as the number of selectors in the table.

If an error occurs, such as an invalid descriptor value or the GDT is full, the EAX and EDX registers contain zero to indicate an error.

Comments

Although this service returns the selector for the GDT, virtual devices should not attempt to edit the GDT directly. Virtual devices can instead use the _SetDescriptor service to change selectors in the GDT.

Virtual devices should use the BuildDescriptorDWORDs service to set the DescDWORD1 and DescDWORD2 parameters to the appropriate values.

This service sets the RPL of the selector to the DPL of the selector set in the DescDWORD1 parameter.

Uses

EAX, EDX

See Also

_Allocate_LDT_Selector, _Free_GDT_Selector


_Allocate_LDT_Selector
include vmm.inc

VMMcall _Allocate_LDT_Selector, <VM, DescDWORD1, DescDWORD2, Count, flags>

The service creates a new selector or selectors and adds them to the Local Descriptor Table (LDT) for the specified virtual machine.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to receive the selectors.

DescDWORD1	Specifies the high four bytes of the descriptor for the selector. This parameter contains the high 16 bits of the base address, the high 4 bits of the limit, and the status and type bits.

DescDWORD2	Specifies the low four bytes of the descriptor for the selector. This parameter contains the low 16 bits of the base address and limit.

Count	Specifies the number of contiguous LDT selectors to allocate if the flags parameter does not specify the ALDTSpecSel value. Otherwise, this parameter specifies the LDT selector to allocate.

flags	Specifies the operation flags. This parameter can be the following value:

Value	Meaning

ALDTSpecSel	Allocates the LDT selector specified by the Count parameter. The service copies the descriptor data to the specified LDT entry and returns the selector. If the LDT selector is already allocated, the service returns an error value instead.

If this value is not given, the service allocates the number of selectors specified by Count.

All other values are reserved.

Returns

If the service is successful, the EAX and EDX registers contain the following values:

Register	Description

EAX	Contains the new selector. If Count is greater than 1, EAX contains only the first selector. The second selector is EAX+8, the third EAX+16, and so on. The high 16 bits of the selector is always zero.

EDX	Contains the selector for and the size of the local descriptor table (LDT). The low 16 bits contains the selector for the LDT, and the high 16 bits contains the size of the LDT expressed as the number of selectors in the table.

The EAX and EDX registers contain zero to indicate an error such as an invalid descriptor value, the LDT is full, an invalid virtual machine handle, or selector already allocated.

Comments

A virtual device can use the selector of the LDT to directly edit the selectors in the LDT. However, a virtual device should use the _SetDescriptor service to change an LDT selector rather than edit the LDT.

This service sets the RPL of the selector to the DPL of the selector set in the DescDWORD1 parameter.

LDT selectors are only valid when the virtual machine for which they are created is the current virtual machine. However, a virtual device can use the _SelectorMapFlat service to examine the region described by a LDT selector in virtual machines which are not the current virtual machine.

Although this service can create multiple selectors, the _Free_LDT_Selector service cannot free multiple selectors. Multiple selectors must be freed individually.

When this service creates multiple selectors, it gives each selector the same descriptor values. It does not change the base address for each selector. It is up to the virtual device to edit the selectors, and assign appropriate base addresses.

Virtual devices should not rely on specific hard-coded LDT selectors, and therefore, they should avoid using the ALDTSpecSel value.

Uses

EAX, EDX

See Also

_Allocate_GDT_Selector, _Free_LDT_Selector


_BuildDescriptorDWORDs
include vmm.inc

VMMcall _BuildDescriptorDWORDs, <DESCBase, DESCLimit, DESCType,

                                 DESCSize, flags>

mov     [DescDWORD1], edx       ; high doubleword of descriptor

mov     [DescDWORD2], eax       ; low doubleword of descriptor

The _BuildDescriptorDWORDs service builds the descriptor parameter used in calls to the _Allocate_GDT_Selector and Allocate_LDT_Selector services.

Parameter	Description

DESCBase	Specifies the 32-bit base address for the descriptor.

DESCLimit	Specifies the 20-bit limit for the descriptor.

DESCType	Specifies the present bit, DPL, and type fields for the descriptor (bits 8-15 of the high doubleword). Only the low 8 bits of the parameter are valid; all other bits must be zero.

DESCSize	Specifies the granularity and big/default fields for the descriptor (bits 20-23 of the high doubleword). Only bits the high four bits (4-7) of the DESCSize parameter are valid; all other bits must be zero.

flags	Specifies the operation flags. This parameter can be the following value:

Value	Meaning

BDDExplicitDPL	Uses the DPL bits in the DESCType parameters. If this value is not given, the service sets the DPL bits to be equal to the RPL bits for protected-mode applications.

All other values are reserved.

Returns

The EAX register contains the low doubleword of the descriptor and the EDX register contains the high doubleword of the descriptor.

Comments

Virtual devices must not rely on the privilege level at which protected-mode applications run. When creating selectors for protected-mode applications, a virtual device should specify the BDDExplicitDPL value. This provides a convenient way to build descriptors without knowing the protection level for protected-mode applications.

Uses

EAX, EDX

See Also

_Allocate_GDT_Selector, _Allocate_LDT_Selector


_Free_GDT_Selector
include vmm.inc

VMMcall _Free_GDT_Selector, <Selector, flags>

or      eax, eax            ; nonzero if freed, zero if error

jz      not_freed

The _Free_GDT_Selector service frees a GDT selector previously allocated using the Allocate_GDT_Selector service.

Parameter	Description

Selector	Specifies the selector to free. This parameter must have been previously created using the Allocate_GDT_Selector service.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error such as an invalid selector.

Comments

Certain system selectors cannot be freed since they are required for Windows operation. This service ignores the RPL bits of the selector.

Uses

EAX

See Also

_Allocate_GDT_Selector, _Free_LDT_Selector


_Free_LDT_Selector
include vmm.inc

VMMcall _Free_LDT_Selector, <VM, Selector, flags>

The _Free_LDT_Selector service frees a LDT selector previously allocated using the _Allocate_LDT_Selector service.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to which the selector belongs.

Selector	Specifies the selector to free. This parameter must have been previously created using the _Allocate_LDT_Selector service.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error, such as an invalid selector or an invalid virtual machine handle.

Comments

This service ignores the RPL bits of the selector.

Uses

EAX

See Also

_Allocate_LDT_Selector, _Free_GDT_Selector


_GetDescriptor
include vmm.inc

VMMcall _GetDescriptor, <Selector, VM, flags>

mov     ecx, eax                ; zero in eax and edx if error

or      ecx, edx

jz      error

mov     [DescDWORD1], edx       ; high doubleword of descriptor

mov     [DescDWORD2], eax       ; low doubleword of descriptor

The _GetDescriptor service retrieves a copy of the descriptor associated with the given LDT or GDT selector.

Parameter	Description

Selector	Specifies a GDT or LDT selector.

VM	Specifies a handle identifying the virtual machine to which the specified LDT selector belongs. The service ignores this parameter if Selector is a GDT selector. Otherwise, the handle must be valid for LDT selectors.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains the low doubleword of the descriptor and the EDX register contain the high doubleword of the descriptor. Both EAX and EDX contain zero to indicate an error, such as an invalid selector or an invalid virtual machine handle.

Comments

This service ignores the high 16-bits of the Selector parameter; the 80386 CPU often sets these bits to random values when doubleword operations are performed on segment registers.

This service ignores the RPL bits of the selector.

Uses

EAX, EDX

See Also

_BuildDescriptorDWORDs, _SetDescriptor


_SetDescriptor
include vmm.inc

VMMcall _SetDescriptor, <Selector, VM, DescDWORD1, DescDWORD2, flags>

or      eax, eax        ; nonzero if set, zero if error

jz      not_set

The _SetDescriptor service sets (changes) the descriptor of the given selector.

Parameter	Description

Selector	Specifies the GDT or LDT selector to set.

VM	Specifies a handle identifying the virtual machine to which the specified LDT selector belongs. The service ignores this parameter if Selector is a GDT selector. Otherwise, the handle must be valid for LDT selectors.

DescDWORD1	Specifies the high doubleword of the descriptor for the selector. This parameter contains the high 16 bits of the base address, the high 4 bits of the limit, and the status and type bits.

DescDWORD2	Specifies the low doubleword of the descriptor for the selector. This parameter contains the low 16 bits of the base address and limit.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error, such as an invalid selector or an invalid virtual machine handle.

Comments

This service ignores the high 16-bits of the Selector parameter; the 80386 CPU often sets these bits to random values when doubleword operations are performed on segment registers.

The service ignores the RPL bits of the selector.

Uses

EAX

See Also

_GetDescriptor


_HeapAllocate
include vmm.inc

VMMcall _HeapAllocate, <nbytes, flags>

or      eax, eax            ; zero if error

jz      not_allocated

mov     [Address], eax      ; address of memory block

The _HeapAllocate service allocates a block of memory from the heap.

Parameter	Description

nbytes	Specifies the size in bytes of the block to allocate. This parameter must not be zero.

flags	Specifies the allocation flags. It can be the following value:

Value	Meaning

HeapZeroInit	Fills the memory block with zeros. If this value is not given, the initial content of the memory block is undefined.

All other values are reserved.

Returns

The EAX register contains the ring-0 address of the block if the service is successful. Otherwise, EAX contains zero to indicate an error such as insufficient memory to satisfy the request.

Comments

This service aligns allocated block on doubleword boundaries, however, the block size does not have to be a multiple of 4.

Since the system offers no protection on the heap, virtual devices must provide their own protection to prevent overrunning allocated blocks.

The system offers no compaction on the heap; all memory blocks on the heap are fixed. Virtual devices must not to use the heap in such a way as to severely fragment it.

Uses

EAX

See Also

_HeapFree, _HeapReAllocate


_HeapFree
include vmm.inc

VMMcall _HeapFree, <hAddress, flags>

or      eax, eax            ; nonzero if freed, zero if error

jz      not_freed

The _HeapFree service frees an existing memory block of heap.

Parameter	Description

hAddress	Specifies the address of the memory block to free. This address must have been previously returned from the _HeapAllocate or _HeapReAllocate service.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error such as an invalid address.

Uses

EAX

See Also

_HeapAllocate, _HeapReAllocate


_HeapGetSize
include vmm.inc

VMMcall _HeapGetSize, <hAddress, flags>

or      eax, eax        ; zero if error

jz      error

mov     [Size], eax     ; size in byte of memory block

The _HeapGetSize service returns the size in bytes of an existing block of heap.

Parameter	Description

hAddress	Specifies the address of the memory block. This address must have been previously returned from the _HeapAllocate or _HeapReAllocate service.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains the size in bytes of the block if the service is successful. Otherwise, EAX contains zero to indicate an error such as an invalid address.

Uses

EAX

See Also

_HeapAllocate


_HeapReAllocate
include vmm.inc

VMMcall _HeapReAllocate, <hAddress, nbytes, flags>

or      eax, eax        ; zero if error

jz      error

mov     [Address], eax  ; address of reallocated block

The _HeapReAllocate service reallocates or reinitializes an existing memory block.

Parameter	Description

hAddress	Specifies the address of the memory block. This address must have been previously returned from the _HeapAllocate or _HeapReAllocate service.

nbytes	Specifies the new size in bytes of the reallocated block. This parameter must not be zero.

flags	Specifies the allocation flags. This parameter can be a combination of the following values:

Value	Meaning

HeapZeroInit	Fills any new bytes in the memory block with zeros. All existing bytes remain unchanged.

HeapZeroReInit	Fills all bytes, new and existing, with zeros.

HeapNoCopy	Does not preserve contents of existing bytes. If this value is not given, the service preserves the contents of existing bytes by copying the contents of the old memory block into the new block.

All other values are reserved.

Returns

The EAX register contains the ring-0 address of the new block if the service is successful. Otherwise, EAX contains zero to indicate an error such as insufficient memory to satisfy the request or an invalid address.

Comments

If this service is successful, it frees the old memory block, making the old address invalid. Virtual devices must never rely on the old and new addresses being the same. If this service returns an error, the old memory block is not freed and the old address remains valid.

Since the system offers no protection on the heap, virtual devices must provide their own protection to prevent overrunning allocated blocks.

The system offers no compaction on the heap; all memory blocks on the heap are fixed. Virtual devices must not not to use the heap in such a way as to severely fragment it.

Uses

EAX

See Also

_HeapAllocate, _HeapFree


_GetV86PageableArray
include vmm.inc

VMMcall _GetV86PageableArray, <VM, <OFFSET32 ArrayBuf>, flags>

or      eax, eax            ; nonzero if array retrieved, zero if error

jz      error

The _GetV86PageableArray service returns a copy of the bit array of pages whose behavior has been modified using the _SetResetV86Pageable service. Virtual devices use this service to determine whether regions in the V86 address space in a virtual machine have had the normal lock and unlock behavior modified.

Parameter	Description

VM	Specifies the virtual machine to examine.

ArrayBuf	Points to the buffer to receive the array. The array contains 100h bits (32 bytes), one bit for each page in the range 0 through 100h. If a bit is set, the lock and unlock behavior for the corresponding page is disabled. Otherwise, the behavior is enabled.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error such as an invalid virtual machine handle.

Comments

This service returns a bit array whose bits are all zero if the VMStat_PageableV86 value is not given in the CB_VM_Status field of the control block for the virtual machine.

Uses

EAX

See Also

_SetResetV86Pageable


_LinMapIntoV86
include vmm.inc

VMMcall _LinMapIntoV86, <HLinPgNum, VM, VMLinPgNum, nPages, flags>

or      eax, eax            ; zero if error

jz      not_mapped

mov     [V86Address], eax   ; V86 address for mapped pages

The _LinMapIntoV86 service maps one or more pages into the V86 address space of the specified virtual machine. This service is similar to the _MapIntoV86 service but uses linear page numbers instead of memory handles. Virtual devices that have access to memory handles should use the MapIntoV86 instead of this service.

Parameter	Description

HLinPgNum	Specifies the linear page number of the first page to map. A linear page number is a ring-0 linear address shifted right by 12 bits.

VM	Specifies a handle identifying the virtual machine for which memory is mapped.

VMLinPgNum	Specifies the linear page number of an address in the V86 address space. The service maps the specified pages to this address if the HLinPgNum parameter does not already specify a valid V86 address. This parameter must be a page number in the range 10h through 10Fh.

nPages	Specifies the number of pages to map.

flags	Specifies the operation flags. This parameter must be set to zero.

Returns

If the EAX register contains a nonzero value, the EDX register contains the V86 address to which the specified pages are mapped. Otherwise, EAX contains zero to indicate an error such as an invalid address range, an invalid virtual machine handle, an illegal map range, a size discrepancy, or insufficient memory locking. The EDX register contents are valid only if the EAX register contains a nonzero value.

Comments

A virtual device typically uses this service to map buffers having protected-mode addresses into the V86 address space. This gives software running in the virtual machine a means of passing data to and receiving data from the virtual device.

If HLinPgNum is a V86 page number (that is less than or equal to 100h), this service returns HLinPgNum immediately and does nothing else. Otherwise, the service returns VMLinPgNum.

If the specified linear pages belong to a free physical region, this service calls the _PhysIntoV86 service to carry out the request.

If the specified linear pages belong to the high addressing region for a virtual machine, this service maps the memory from that virtual machine into the virtual machine specified by the VM parameter. The V86MMGR device uses this capability to map a region of V86 address space which is currently local to one VM into a global region that is addressable by all virtual machines. Virtual devices must not use this capability directly; they should always use the V86MMGR services to map local memory into global memory.

Although a virtual device can map the same page into multiple addresses in the V86 address space, this is not recommended.

For each mapped page, this service sets the P_USER, P_PRES, and P_WRITE bits, but clears the P_DIRTY and P_ACC bits. The service sets the page type to be identical to the page type for the pages at the specified protected-mode linear address.

If the virtual pageswap device uses MS-DOS or BIOS functions to write to the device, this service automatically locks all mapped pages and unlocks any previously mapped pages.

If a virtual device no longer needs the mapped region, it should map the system nul page into the V86 address space using the _MapIntoV86 service. A virtual device can retrieve the handle for the system nul page using the _GetNulPageHandle service.

This service accepts V86 page numbers between 10h and the page number returned by the _GetFirstV86Page service. This supports virtual devices that use the _Allocate_Global_V86_Data_Area service. Mapping a region which spans across the first V86 page is not allowed. Mapping pages in this region to other addresses can easily crash the system, and should be avoided.

Uses

EAX, EDX

See Also

_Allocate_Global_V86_Data_Area, _GetFirstV86Page, _GetNulPageHandle, _MapIntoV86, _PageLock, _PhysIntoV86


_LinPageLock
include vmm.inc

VMMcall _LinPageLock, <HLinPgNum, nPages, flags>

or      eax, eax                ; nonzero if locked, zero if error

jz      not_locked

The _LinPageLock service unlocks one or more pages starting at the specified linear page number. This service is similar to the _PageLock service, but uses linear page numbers instead of memory handles.

Parameter	Description

HLinPgNum	Specifies the linear page number of the first page to lock. A linear page number is a ring-0 linear address shifted right by 12 bits.

nPages	Specifies the number of pages to lock.

flags	Specifies the operation flags. This parameter can be the following value:

Value	Meaning

PageLockedIfDP	Locks pages only if the virtual pageswap device use MS-DOS or BIOS functions to write pages to the hardware. If the virtual pageswap device writes directly to hardware, this service returns immediately without locking the pages.

All other values are reserved.

Returns

The EAX register contains a nonzero value if the lock is successful. Otherwise, EAX contains zero to indicate an error such as an invalid address range or insufficient memory for locking.

See Also

_LinMapIntoV86, _LinPageUnLock, _PageLock


_LinPageUnLock
include vmm.inc

VMMcall _LinPageUnLock, <HLinPgNum, nPages, flags>

or      eax, eax                ; nonzero if unlocked, zero if error

jz      not_unlocked

The _LinPageUnLock service unlocks one or more pages starting at the specified linear page number. This service is similar to the _PageUnLock service, but uses linear page numbers instead of memory handles.

Parameter	Description

HLinPgNum	Specifies the linear page number of the first page to unlock. A linear page number is a ring-0 linear address shifted right by 12 bits.

nPages	Specifies the number of pages to unlock.

flags	Specifies the operation flags. This parameter can be a combination of the following values:

Value	Meaning

PageLockedIfDP	Unlocks pages only if the virtual pageswap device use MS-DOS or BIOS functions to write to the hardware. If the virtual pageswap device writes directly to the hardware, this service returns immediately without unlocking the pages.

PageMarkPageOut	Marks pages for immediate swapping if this service sets the lock count for the pages to zero. This service marks the pages by clearing the P_ACC bit for each page. The PageMarkPageOut value should only be used if the pages are unlikely to be accessed for some time.

All other values are reserved.

Returns

The EAX register contains a nonzero value if the unlock is successful. Otherwise, EAX contains zero to indicate an error, such as an invalid address range.

Uses

EAX

See Also

_LinMapIntoV86, _LinPageLock, _PageUnLock


_PageCheckLinRange
include vmm.inc

VMMcall _PageCheckLinRange, <HLinPgNum, nPages, flags>

cmp     eax, 0              ; zero if not valid

je      not_valid

mov     [Pages], eax        ; actual number of pages in valid range

The _PageCheckLinRange service determines whether all bytes in the specified range of linear addresses are valid. Virtual devices typically use this service to validate an address range before specifying the range in a call to the _LinPageLock or _LinMapIntoV86 service.

Parameter	Description

HLinPgNum	Specifies the linear page number of the first page to check. A linear page number is a ring-0 linear address shifted right by 12 bits.

nPages	Specifies the number of pages to check.

flags	Specifies the operation flags. This parameter must be zero.

Returns

The EAX register contains the actual number of pages which contain valid addresses. This value is zero if the entire range is invalid.

Uses

EAX

See Also

_LinMapIntoV86, _LinPageLock


_PageDiscardPages
include vmm.inc

VMMcall _PageDiscardPages, <LinPgNum, VM, nPages, flags>

or      eax, eax            ; nonzero if discarded, zero if error

jz      not_discarded

The _PageDiscardPages service marks pages as no longer in use, allowing the system to discard the pages. Subsequent attempts to access the page do not cause the system to read the previous contents of the page from disk.

Parameter	Description

LinPgNum	Specifies linear page number of the first page to discard. If this parameter is less than 110h or corresponds to a virtual machine high linear address, the VM parameter must specify a valid virtual machine handle. All pages of the specified range must be marked V86Pageable.

VM	Specifies a handle identifying the virtual machine containing the pages to discard.

nPages	Specifies the number of pages to discard.

flags	Specifies the operation flags. This parameter can be a combination of the following values:

Value	Meaning

PageZeroInit	Fills the specified pages with zeros when a subsequent attempt to page in the pages is made. This value only applies when the PageDiscard value is also given. If this value is not given, the content of the pages is undefined.

PageDiscard	Marks pages for a full discard by clearing both the P_ACC and P_DIRTY bits in the page table entries. If this value is not given, this service only clears the P_ACC bit in the page table entries.

All other values are reserved.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise EAX contains zero indicating an error, such as an invalid range or an invalid virtual machine handle.

Comments

This service ignores pages in the range which are not present or are locked. This service affects only pages that are subject to demand paging.

Uses

EAX


_SelectorMapFlat
include vmm.inc

VMMcall _SelectorMapFlat, <VM, Selector, flags>

cmp     eax, 0FFFFFFFFh         ; 0FFFFFFFFh if error

je      error

mov     [Address], eax          ; base address of selector

The _SelectorMapFlat service returns the base address of the specified GDT or LDT selector. The address mapper uses this service to convert pointers, consisting of selector and offset pairs, to flat-model linear addresses suitable for use as parameters for the _LinMapIntoV86 service.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to which the specified selector belongs. This parameter is not used if Selector is a GDT selector. This parameter must be valid for LDT selectors.

Selector	Specifies a GDT or LDT selector.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains the linear address of the base of the selector if the service is successful. Otherwise, EAX contains 0FFFFFFFFh to indicate an error, such as an invalid selector.

Comments

This service ignores the high 16 bits of the Selector parameter; the 80386 CPU often sets these bits to somewhat random values when doubleword operations are performed on segment registers.

Uses

EAX

See Also

_LinMapIntoV86


_SetResetV86Pageable
include vmm.inc

VMMcall _SetResetV86Pageable, <VM, VMLinPgNum, nPages, flags>

or      eax, eax    ; nonzero if set or reset, zero if error

jz      error

The _SetResetV86Pageable service modifies the locking and unlocking behavior associated with a specific range of V86 memory.

Parameter	Description

VM	Specifies a handle identifying the virtual machine for which the behavior is modified.

VMLinPgNum	Specifies the linear page number of the first page in 1 megabyte V86 address space to modify. This parameter must not be below the page number for the first V86 page or above 100h.

nPages	Specifies the number of pages to modify.

flags	Specifies the operation flags. This parameter can be one of the following values:

Value	Meaning

PageSetV86Pageable	Disable normal locking behavior of _MapIntoV86 and let V86 memory be paged.

PageClearV86Pageable	Enable normal locking behavior.

PageSetV86IntsLocked	Enable locking of all V86 memory that is not pageable regardless of whether the virtual pageswap device uses MS-DOS or BIOS functions.

PageClearV86IntsLocked	Disable locking of all V86 memory that is not pageable regardless of whether the virtual pageswap device uses MS-DOS or BIOS functions.

All other values are reserved.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error, such as an invalid virtual machine handle or an invalid address range.

Comments

This service is intended to be used to support protected-mode applications running in a virtual machine. Virtual devices must not use this service for any other purpose.

This service returns an error if the VMStat_PageableV86 or VMStat_V86IntsLocked state is inconsistent with the specified PageSetV86Pageable, PageClearV86Pageable, PageSetV86IntsLocked, or PageClearV86IntsLocked values.

This service returns an error if the PageClearV86Pageable or PageSetV86IntsLocked values are given, but the service cannot lock the specified memory.

The V86MMGR device uses the PageSetV86IntsLocked value for virtual machines which are created with their base memory specified as locked.

Virtual device should avoid manipulating the locking and unlocking behavior of regions above page 0A0h. A virtual device should not modify these pages unless it owns a global or local region set by the _Assign_Device_V86_Pages service.

If the PageSetV86IntsLocked or PageClearV86IntsLocked value is given, the service applies the modification to every page that that is not pageable. For this reason the HLinPgNum and nPages parameters should be set to zero.

By default, the _MapIntoV86 service locks the memory it maps. For a virtual machine running a protected-mode application, it is desirable change this default behavior.

Uses

EAX

See Also

_Assign_Device_V86_Pages


_AddInstanceItem
include vmm.inc

VMMcall _AddInstanceItem, <<OFFSET32 InstStruc>, flags>

or      eax, eax        ; nonzero if added, zero if error

jz      not_added

The _AddInstanceItem service identifies a region of instance data in the V86 address space.

Parameter	Description

InstStruc	Points to an InstDataStruc structure containing information about the block of memory to instance.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise EAX contains zero to indicate an error.

Comments

To prevent errors, a virtual device must not change the location and content of any InstDataStruc structures until after the system has completed its initialization. To achieve this, a virtual can either staticly allocate the structures in its INIT data segment or dynamically allocate the structures on the system heap using the _HeapAllocate service. If the structures are in the INIT data segment, the system automatically frees the structure when it reclaims the INIT segment space. If the structures are in the system heap, the virtual device must free the structures using the _HeapFree service while processing the Sys_VM_Init message.

If a virtual device the structures on the system heap, it must not attempt to reallocate the structure before system initialization has completed since this invalidates the structure address.

Only one, contiguous region of instance data can be identified with each structure. The virtual device can cut down the call overhead and data space requirements by coalescing adjacent blocks of instance data and identifying the coalesced blocks as a single instance item.

Uses

EAX

See Also

InstDataStruc


_Allocate_Device_CB_Area
include vmm.inc

VMMcall _Allocate_Device_CB_Area, <nBytes, flags>

or      eax, eax        ; zero if error

jz      not_allocated

mov     [Offset], eax   ; offset from start of control block to new area

The _Allocate_Device_CB_Area service allocates an area in the control block of the current virtual machine for exclusive use by the virtual device. Virtual devices typically uses this service to allocate space to store data that is specific to a given virtual machine.

This service is only available during initialization.

Parameter	Description

nBytes	Specifies the number of bytes to allocate.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains the offset from the start of the control block to the new area if the service is successful. Otherwise, EAX contains zero to indicate an error such as insufficient memory to satisfy the request.

Comments

If this service returns an error, the virtual device should consider this a fatal error and respond accordingly.

Although this service aligns the new area on a doubleword boundary and rounds the nBytes parameter up to the next multiple of 4, the virtual device must not rely on this behavior.

The service fills the newly allocated area with zeros. When the system creates a new virtual machine, it fills all bytes of the control block with zeros.

Uses

EAX

See Also

Control_Block


_MapPhysToLinear
include vmm.inc

VMMcall _MapPhysToLinear, <PhysAddr, nBytes, flags>

cmp     eax, 0FFFFFFFFh     ; 0FFFFFFFFh if not addressable

je      not_addressable

mov     [Address], eax      ; address of first byte

The _MapPhysToLinear service returns the linear address of the first byte in the specified range of physical addresses.

Parameter	Description

PhysAddr	Specifies the 32-bit physical address of the start of the region to examine. Physical addresses start at 0, thus the address of physical page 0A0h is 0A0000h.

nBytes	Specifies the length in bytes of the physical region. The service uses this parameter to verify that the entire range is addressable.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains the ring-0 linear address of the first byte of the physical region if this service is successful. Otherwise, EAX contains 0FFFFFFFFh if the specified range is not addressable.

Comments

This service is intended to be used to examine device-specific physical memory. Virtual devices must not use this service for any other purpose.

Since physical addresses do not move, the linear address returned by this service remains valid even after the virtual device returns from the Device_Init message.

Example

The following example returns a linear address for the physical page A0h:

VMMcall _MapPhysToLinear,<0A0000h,10000h,0>

Since physical memory is mapped contiguously, the linear address for page 0A1h is 4096 bytes beyond the return linear address.

Uses

EAX


_CopyPageTable
include vmm.inc

VMMcall _CopyPageTable, <LinPgNum, nPages, <OFFSET32 PageBuf>, flags>

mov     [Copied], eax           ; nonzero if copied, zero otherwise

The _CopyPageTable service copies one or more page-table entries to the specified buffer. Virtual devices, such as the virtual DMA device, use this service to analyze the mapping of linear to physical addresses.

Parameter	Description

LinPgNum	Specifies the number of the first page table entry to copy. This parameter must be in the range 0 through 0FFFFFh. Numbers in the range 0 through 10Fh specify pages in the 1 megabyte V86 address space of the current virtual machine. Page numbers for other virtual machines can be computed using the CB_High_Linear field in the control block of each virtual machine.

nPages	Specifies the number of page table entries to copy.

PageBuf	Points to buffer to receive the page table entries. This buffer must be large enough to receive the specified number of entries. Each entry is 4 bytes.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the copy is successful. Otherwise, it contains zero indicating that at least one of the specified page table entries was in a region where the corresponding page directory entry is not present.

Comments

This service copies the page table, so writing to the buffer does not affect the content of the actual page table. The system does not update the buffer when changes to the actual page table are made, so no guarantees are made about the length of time the information in the buffer remains accurate.

Uses

EAX


_GetAppFlatDSAlias
include vmm.inc

VMMcall _GetAppFlatDSAlias

mov     [FlatData], eax         ; read-only GDT selector

The _GetAppFlatDSAlias service returns a ring-3, read-only, GDT selector that provides access to the same memory as the system's ring-0 data segment selector. Virtual devices use this service to support protected-mode APIs that let protected-mode applications read from the same memory as the virtual device.

This service has no parameters.

Returns

The EAX register contains the selector.

Comments

Since more than one virtual device may use this selector, a virtual device must never attempt to free the selector using the _Free_GDT_Selector service. Also, a virtual device should not attempt to create a read/write selector using this selector. If a virtual device requires an application to write to any portion of system memory, the virtual device should build its own selector with a base and limit that specifies just the memory the application must modify.

Uses

EAX

See Also

_Free_GDT_Selector


_GetDemandPageInfo
include vmm.inc

VMMcall _GetDemandPageInfo, <<OFFSET32 DemandInfo>, flags>

The _GetDemandPageInfo service retrieves information used for demand paging, copying the information to the specified structure. This service is for exclusive use by the virtual paging device.

Parameter	Description

DemandInfo	Points to a DemandInfoStruc structure containing information for demand paging.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

This service has no return value.

Uses

Flags

See Also

DemandInfoStruc


_GetFirstV86Page
include vmm.inc

VMMcall _GetFirstV86Page

mov     [FirstPage], eax        ; first page of V86 memory

The _GetFirstV86Page service returns the page number of the first page in the current virtual machine.

This service has no parameters.

Returns

The EAX register contains the page number of the first page.

Comments

The first page in a virtual machine moves during virtual device initialization, so the page number returned by this service during initialization will not be valid at any later time.

Uses

EAX

See Also

_GetLastV86Page


_GetFreePageCount
include vmm.inc

VMMcall _GetFreePageCount, <flags>

mov     dword ptr [FreePages], eax      ; number of free pages

mov     dword ptr [LockablePages], edx  ; number of lockable pages

The _GetFreePageCount service returns the number of pages in the free list. This service also returns the number of free pages that can be allocated as locked pages. Virtual devices can allocate free pages using the _PageAllocate service.

Parameter	Description

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains the count of free pages, and the EDX register contains the count of pages available for allocation as locked pages.

Comments

In a demand-paged virtual memory system such as Windows, the number of free pages is usually very close to 0, so the count of pages available for locking is usually a better indicator of available memory. However, virtual devices must not rely on the count of free pages being less than or equal to the count of pages to lock. No guarantees can be made about the length of time the information returned by this service remains accurate.

Uses

EAX, EDX

See Also

_PageAllocate


_GetGlblRng0V86IntBase
include vmm.inc

VMMcall _GetGlblRng0V86IntBase

mov     [Address], eax      ; address for ring-0 V86 interrupt handlers

The _GetGlblRng0V86IntBase service returns the linear address used to manage ring-0 global V86 interrupt handlers.

This service is only available during initialization, and only available for Windows version 3.1 or later.

This service has no parameters.

Returns

The EAX register contains the linear address of the ring-0 handler.

Comments

Ring-0 global V86 interrupt handlers require segment selectors that permit execution in protected mode at ring 0. Furthermore, the selectors must represent memory that is not subject to page faults. Page faults are a potential problem because part of the global code or data for a ring-0 V86 interrupt handler may overlap with the noninstanced part of an instance data page.

This service returns the linear address of the start of a V86 address space in which instance data pages are always present. The linear address is a duplicate of the V86 address 0:0 in the system virtual machine. The size of this duplicate mapping is 1 megabyte plus 64 kilobytes. This address space includes the xMS HMA (pages 100h-10Fh). The system sets up the duplicate mapping after all virtual devices have processed the Sys_Critical_Init message. The A20 state of the system virtual machine, or any other virtual machine, has no effect on the mapping used for this address space. The physical (global) HMA is always mapped in this address space. Thus, A20 is effectively always on (HMA always enabled).

Virtual devices that use this address space must wait until the Device_Init or Init_Complete message to request the address. This service returns zero if a virtual device attempts to retrieve the address while processing the Sys_Critical_Init message. If a virtual device needs the address sooner than receipt of the Device_Init message, the virtual device can use a base address of 0 to build the selectors. It can then edit the selectors when it processes the Device_Init message, changing the base address to the correct location by adding in the return value from this service.

Ring-0 global V86 interrupt handlers may only access global memory.

Instance data does not work properly in this address space. The local part of this address space is mapped with the system nul page.

Uses

EAX


_GetLastV86Page
include vmm.inc

VMMcall _GetLastV86Page

mov     [LastPage], eax     ; last page in V86 memory

The _GetLastV86Page service returns the page number of the last page of V86 memory for the specified virtual machine.

This service is only available for Windows version 3.1 or later.

This service has no parameters.

Returns

The EAX register contains the page number of the last page in V86 memory.

Comments

The last page in V86 memory moves during initialization. Virtual devices that retrieve the last page when processing initialization messages must retrieve the page number again to use it later.

Uses

EAX

See Also

_GetFirstV86Page


_GetNulPageHandle
include vmm.inc

VMMcall _GetNulPageHandle

mov     [NulPage], eax          ; handle of system nul page

The _GetNulPageHandle service returns the memory handle of the system nul page. This page is used to occupy regions of the address space which are unused but for which it is not desirable to cause a page fault when accessed. The system nul page can be mapped to multiple locations in the system, so its contents are always random.

This service has no parameters.

Returns

The EAX register contains the memory handle of the system nul page.

Uses

EAX

See Also

_MapIntoV86


_GetSysPageCount
include vmm.inc

VMMcall _GetSysPageCount, <flags>

mov     [SysPages], eax         ; count of system pages

The _GetSysPageCount service returns the current count of system pages. System pages are pages that have been allocated using the PG_SYS value.

Parameter	Description

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains the number of pages allocated as PG_SYS pages.

Comments

Although the return value often is equal to the size of the Windows virtual machine manager, virtual devices must not rely on this fact.

Uses

EAX

See Also

_GetFreePageCount, _GetVMPgCount


_GetVMPgCount
include vmm.inc

VMMcall _GetVMPgCount, <VM, flags>

The _GetVMPgCount service returns the current count of pages allocated to a particular virtual machine.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to examine.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains the total number of pages allocated for the specified virtual machine, and the EDX register contains the count of pages which are allocated to this virtual machine but which are not mapped into the virtual machine's 1 megabyte address space.

Both EAX and EDX contain zero to indicate an error, such as an invalid virtual machine handle.

Comments

Virtual devices must not rely on the sum of the return values being the size (in pages) of the virtual machine.

Uses

EAX, EDX

See Also

_GetFreePageCount, _GetSysPageCount


_ModifyPageBits
include vmm.inc

VMMcall _ModifyPageBits, <VM, VMLinPgNum, nPages, bitAND, bitOR,

                          pType, flags>

or      eax, eax            ; nonzero if modified, zero if error

jz      not_modified

The _ModifyPageBits service modifies the page attribute bits associated with PG_HOOKED pages in the V86 address space of a virtual machine. Virtual devices use this service to modify the P_PRES, P_WRITE, and P_USER bits and the PG_TYPE, if appropriate.

Parameter	Description

VM	Specifies a handle identifying the virtual machine owning the pages to modify.

VMLinPgNum	Specifies the linear page number of the first page to modify. All pages must be in the 1 megabyte V86 address space. Page numbers below the first page of the specified virtual machine or above 10Fh cause an error.

nPages	Specifies the number of pages to modify.

bitAND	Specifies the AND mask for the page attribute bits. All AND mask bits, except the P_PRES, P_WRITE, and P_USER bits, must be set to 1. The P_PRES, P_WRITE, and P_USER bits can be 0 or 1 to clear or preserve the corresponding page attributes.

bitOR	Specifies the OR mask for the page attribute bits. All bits, except the P_PRES, P_WRITE, and P_USER bits, must be set to 0. The P_PRES, P_WRITE, and P_USER bits can be 0 or 1 to preserve or set the corresponding page attributes.

pType	Specifies the page type. It can be one of the following values:

Value	Meaning

PG_HOOKED	Changes the page type to hooked. This value must be specified if the service clears any one of the P_PRES, P_WRITE and P_USER bits.

PG_IGNORE	Leaves the current page type unchanged.

All other values are reserved.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error such as an invalid virtual machine handle, invalid bits in AND and OR masks, an invalid type, or a bad page range.

Comments

This service always clears the P_DIRTY and P_ACC bits regardless of the AND and OR mask values.

If a virtual device clears the P_PRES, P_WRITE, or P_USER bits, the virtual device must set the page type for all such pages to PG_HOOKED. Also the virtual device must have previously installed a hook page fault handler for these pages.

This service cannot be used to set the P_PRES bit. Virtual devices can use the _MapIntoV86 or _PhysIntoV86 service to make pages present. Since the _MapIntoV86 service resets the page type to the same page type as the memory specified by the memory handle, the virtual devices should set the page type to PG_HOOKED when it creates the memory handle using the _PageAllocate service. Since the _PhysIntoV86 service sets the page type to PG_SYS, the virtual devices must use the _ModifyPageBits service to change the page type to PG_HOOKED if it uses _PhysIntoV86 to map physical pages into a hooked page region.

If using the P_WRITE bit to simulate ROM in a virtual machine, a virtual device should map the pages using the _PhysIntoV86 service and immediately call the _ModifyPageBits service to clear the P_WRITE bit and change the page type to PG_HOOKED.

Uses

EAX

See Also

_MapIntoV86, _PhysIntoV86


_PageAllocate
include vmm.inc

VMMcall _PageAllocate, <nPages, pType, VM, AlignMask, minPhys,

                maxPhys, <OFFSET32 PhysAddr>, flags>

mov     ecx, eax                ; zero in eax and edx if error

or      ecx, edx

jz      error

mov     [Handle], eax           ; memory handle

mov     [Address], edx          ; ring-0 address of memory block

The _PageAllocate service allocates a block of memory consisting of the specified number of pages. This service reserves linear address space for the memory block, and depending on the value of the flags parameter, may also map the linear addresses to physical memory, locking the pages in memory. The service returns a memory handle that can be used in subsequent memory management functions to lock, unlock, reallocate, and free the memory block.

Parameter	Description

nPages	Specifies the number of pages to allocate for the memory block. This parameter must not be zero.

pType	Specifies the type of pages to allocate. It can be one of the following values:

Value	Meaning

PG_VM	Allocates pages that are specific to a particular virtual machine. The handle of PG_VM memory blocks will typically be placed in the virtual machine's control block.

PG_SYS	Allocates global system pages that are valid in all virtual machines.

PG_HOOKED	Allocates pages that are mapped into the virtual machine at locations for which a page-fault handler has been installed. These pages are specific to a particular virtual machine.

VM	Specifies a handle identifying the virtual machine for which to allocate the pages. This parameter applies to pages allocated using the PG_VM and PG_HOOKED values only. This parameter must be set to zero when using the PG_SYS value.

AlignMask	Specifies an alignment mask that defines acceptable starting page numbers for the memory block. This parameter can be one of the following values:

Value	Meaning

00000000h	Physical address is a multiple of 4K.

00000001h	Physical address is a multiple of 8K.

00000003h	Physical address is a multiple of 16K.

00000007h	Physical address is a multiple of 32K.

0000000Fh	Physical address is a multiple of 64K.

0000001Fh	Physical address is a multiple of 128K.

This parameter is used only if the flags parameter specifies the PageUseAlign value.

minPhys	Specifies the minimum acceptable physical page number in the memory block. All page numbers must be greater than or equal to this value. This parameter is used only if the flags parameter specifies the PageUseAlign value.

maxPhys	Specifies the maximum acceptable physical page number in the memory block. All page numbers must be less than this value. This parameter is used only if the flags parameter specifies the PageUseAlign value.

PhysAddr	Points to the four-byte buffer to receive the physical address of the start of the memory block. The service uses this parameter only if the flags parameter specifies the PageUseAlign value.

flags	Specifies the operation flags. This parameter can be a combination of the following values:

Value	Meaning

PageZeroInit	Fills the memory block with zeros. If this value is not given, the contents of the memory block are undefined.

PageUseAlign	Allocates pages using the alignment and physical addresses specified by the AlignMask, minPhys, and maxPhys parameters. The PageUseAlign value is only available during initialization and can only be used in combination with the PageFixed value.

PageContig	Allocates contiguous physical pages to create the memory block. This value is ignored if the PageUseAlign value is not also specified.

PageFixed	Locks the allocated pages in memory at a fixed linear address and prevents the pages from subsequently being unlocked or moved. The service locks the memory block regardless of the type of virtual pageswap device present.

PageLocked	Locks the allocated pages in the memory. The pages can be subsequently unlocked using the _PageUnLock service. The service locks the memory block regardless of the type of virtual pageswap device present.

PageLockedIfDP	Locks the allocated pages in the memory only if the virtual pageswap device uses MS-DOS or BIOS functions to write to the hardware. If the pages are locked, they can be subsequently unlocked using the _PageUnLock service.

A virtual device must not specify the PageLockedIfDP value until after it has received the Init_Complete message.

The PageLocked and PageLockedIfDP values are mutually exclusive.

PageMapFreePhysReg	Allocates a free physical region which a virtual device may use to map physical pages that otherwise are placed in the system's free memory pool. The nPages parameter specifies the number of pages in the region. The pType parameter must be set to PG_SYS and the VM, AlignMask, minPhys, maxPhys, and PhysAddrPTR parameters must be set to zero. A free physical region cannot be reallocated or freed; these regions exist for the duration of the Windows session.

This value is only available during initialization, and only in Windows version 3.1 or later.

All other values are reserved.

Returns

The EAX register contains the memory handle of the block, and the EDX register contains the ring-0 linear address of the memory block. Otherwise, the EAX and EDX registers both contain zero to indicate an error such insufficient memory to satisfy the request.

Comments

Unless PageLocked, PageLockedIfDP, or PageFixed is specified, this service allocates linear address space without mapping the addresses to physical memory. In this case, the system maps the physical page when the virtual device attempts to access an address in the address space. A virtual device can also use the _PageLock service to force this mapping.

Virtual devices use the PageUseAlign value to allocate buffers for use by the device which have additional alignment restrictions enforced by the hardware. For example, a DMA may require buffers to start at addresses that are a multiple of 64K or 128K. When allocating such buffers, the PageContig value is often used in combination with PageUseAlign.

The action specified by the PageLockedIfDP value is available only after the virtual pageswap device has been initialized.

Virtual devices must never rely on apparent relationships between the memory handle and the ring-0, or physical address of a memory block.

All pages in the free physical region are initially not present. Virtual devices use the MapFreePhysReg service to map physical pages into the region and use the UnmapFreePhysReg service to remove pages from the region. Since the system does not provide a backing store for a free physical region, unmapping a page makes the previous contents unrecoverable. The MapFreePhysReg and UnmapFreePhysReg services can only be be used within a free-physical-region callback procedure installed using the _SetFreePhysRegCalBk service.

Uses

EAX, EDX

See Also

_PageFree, _PageLock, _PageReAllocate, _PageUnLock


_PageFree
include vmm.inc

VMMcall _PageFree, <hMem, flags>

or      eax, eax        ; nonzero if freed, zero if error

jz      not_freed

The _PageFree service frees the specified memory block.

Parameter	Description

hMem	Specifies a handle identifying the memory block to free. This handle must have been previously created using the _PageAllocate or _PageReAllocate service.

flags	Specifies the operation flags. This parameter must be set to zero.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error, such as an invalid memory handle.

Comments

Virtual devices that allocate PG_VM or PG_HOOKED pages must free these pages when the associated virtual machine is destroyed. PG_SYS pages do not need to be freed when Windows exits.

If a virtual device maps a memory block into the V86 address space (using the _MapIntoV86 service), it should unmap the memory block before attempting to free it.

It is not an error to free memory which is all or partially locked.

Uses

EAX

See Also

_PageAllocate, _PageReAllocate


_PageGetAllocInfo
include vmm.inc

VMMcall _PageGetAllocInfo, <flags>

mov     [Free], eax         ; count of free pages

mov     [Lockable], edx     ; count of lockable pages

The _PageGetAllocInfo service returns the size in pages of the largest block of linear address space that can be allocated. It also returns the number of pages that can be allocated as locked or fixed memory.

Parameter	Description

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a count of free pages available, and the EDX register contains a count of pages available for allocating as locked pages.

Comments

Virtual devices must not rely on being able to allocate all pages specified by this service. In general, virtual devices should allocate memory as needed, and not attempt to allocate all available memory.

Virtual device must not rely on the count of free pages being greater than or equal to the count of pages available for locking.

Uses

EAX, EDX

See Also

_PageAllocate


_PageGetSizeAddr
include vmm.inc

VMMcall _PageGetSizeAddr, <hMem, flags>

mov     ecx, eax            ; zero in eax and edx if error

or      ecx, edx

jz      error

mov     [Pages], eax        ; number of pages in memory block

mov     [Address], edx      ; ring-0 linear address of memory block

The _PageGetSizeAddr service returns the size and linear address of an existing block of memory.

Parameter	Description

hMem	Specifies a handle identifying the memory block for which to return information. This handle must have been previously created using the _PageAllocate or _PageReAllocate service.

flags	Specifies the operation flags. This parameter must be set to zero.

Returns

The EAX register contains the number of pages in the memory block, and EDX register contains the ring-0 linear address of the memory block. The EAX and EDX registers both contain zero to indicate an error, such as an invalid memory handle.

Comments

The returned number of pages specifies the total size of the block, not just the number of pages currently present.

Uses

EAX, EDX

See Also

_PageAllocate, _PageReAllocate


_PageLock
include vmm.inc

VMMcall _PageLock, <hMem, nPages, PageOff, flags>

or      eax, eax        ; nonzero if locked, zero if error

jz      not_locked

The _PageLock service locks one or more pages in the specified memory block.

Parameter	Description

hMem	Specifies a handle identifying the memory block to lock. This handle must have been previously created using the _PageAllocate or _PageReAllocate service.

nPages	Specifies the number of pages to lock.

PageOff	Specifies the offset in pages from the start of the memory block to the first page to lock.

flags	Specifies the operation flags. This parameter can be the following value:

Value	Meaning

PageLockedIfDP	Lock pages only if the virtual pageswap device uses MS-DOS or BIOS function to write pages to the hardware. If the virtual pageswap device writes directly to the hardware, this service returns immediately without locking the pages.

The PageLockedIfDP value cannot be used until after the Init_Complete message has been processed.

All other values are reserved.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error, such as invalid memory handle or insufficient memory.

Comments

This service returns an error if the sum of the PageOff and nPages parameters is greater than the number of pages in the memory block.

This service has no affect on memory blocks allocated using the PageFixed value; such memory is always locked.

Virtual devices must not assume that the requested number of pages can always be locked.

Each page in a memory block has an individual lock count. This service increments the lock count each time the page is locked, and decrements the count each time the page is unlocked. The lock count must be zero for the page to be unlocked. This means that if the handle is locked 5 times, it has to be unlocked 5 times. Virtual devices must not leave handles locked when not needed.

Uses

EAX

See Also

_PageAllocate, _PageUnlock


_PageReAllocate
include vmm.inc

VMMcall _PageReAllocate, <hMem, nPages, flags>

mov     ecx, eax                ; zero in eax and edx if error

or      ecx, edx

jz      error

mov     [Handle], eax           ; memory handle

mov     [Address], edx          ; physical address of start of memory block

The _PageReAllocate service reallocates and optionally reinitializes an existing memory block. The service can increase or decrease the number of pages in the memory block.

Parameter	Description

hMem	Specifies a handle identifying the memory block to reallocate. This handle must have been previously created using the _PageAllocate or _PageReAllocate service.

nPages	Specifies the number of pages in the reallocated memory block. This parameter must not be set to zero. To free a memory block, use the _PageFree service.

flags	Specifies the operation flags. This parameter can be a combination of the following values:

Value	Meaning

PageZeroInit	Fills any new pages with zeros. All existing pages remain unchanged.

PageZeroReInit	Fills all pages, new and existing, with zeros.

PageNoCopy	Does not preserve contents of existing pages. If this value is not given, the service preserves the contents of each existing page by copying the contents of the old memory block into the corresponding pages of the new block.

PageLocked	Locks the allocated pages in the memory. The pages can be subsequently unlocked using the _PageUnLock service. The service locks the memory block regardless of the type of virtual pageswap device present.

PageLockedIfDP	Locks the allocated pages in the memory only if the virtual pageswap device uses MS-DOS or BIOS functions to write to the hardware. If the pages are locked, they can be subsequently unlocked using the _PageUnLock service.

A virtual device must not specify the PageLockedIfDP value until after the Init_Complete message has been processed by all virtual devices.

All other values are reserved.

Returns

The EAX register contains the memory handle of the new memory block, and the EDX register contains the ring-0 linear address of the block. Otherwise, the EAX and EDX registers both contain zero to indicate an error such as insufficient memory, an invalid memory handle, or wrong memory type.

Comments

If successful, this service frees the old memory block, making the old memory handle and starting address invalid. If this service returns an error, the old memory handle and starting address remain valid.

If the specified memory handle identifies a fixed memory block (allocated using the PageFixed value), this service implicitly allocates fixed pages for the new memory block.

If the specified handle identifies an aligned memory block (allocated using the PageUseAlign value), this service returns an error.

Virtual devices must never rely on the new and old memory handles being the same, or the new and old starting addresses being equal.

The action specified by the PageLockedIfDP value is available only after the virtual pageswap device has been initialized.

Uses

EAX, EDX

See Also

_PageAllocate, _PageFree, _PageLock, _PageUnLock


_PageUnLock
include vmm.inc

VMMcall _PageUnLock, <hMem, nPages, PageOff, flags>

or      eax, eax            ; nonzero if unlocked, zero if error

jz      not_unlocked

The _PageUnLock service unlocks one or more pages in the specified memory block.

Parameter	Description

hMem	Specifies a handle identifying the memory block to unlock. This handle must have been previously created using the PageAllocate or PageReAllocate service.

nPages	Specifies the number of pages to unlock.

PageOff	Specifies the offset in pages from the start of the block to the first page to unlock.

flags	Specifies the operation flags. This parameter can be a combination of the following values:

Value	Meaning

PageLockedIfDP	Unlock pages only if the virtual pageswap device use MS-DOS or BIOS functions to write to the hardware. If the virtual pageswap device writes directly to the hardware, this service returns immediately without unlocking the pages.

The PageLockedIfDP value cannot be used until after the Init_Complete message has been processed.

PageMarkPageOut	Marks pages for immediate swapping if this service sets the lock count for the pages to zero. This service marks the pages by clearing the P_ACC bit for each page. The PageMarkPageOut value should only be used if the pages are unlikely to be accessed for some time.

All other values are reserved.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error, such as an invalid memory handle.

Comments

This service returns an error if the sum of the PageOff and nPages parameters is greater than the number of pages in the memory block. It also returns an error if the specified pages are not already locked.

Each page in a memory block has an individual lock count. This service increments the lock count each time the page is locked, and decrements the count each time the page is unlocked. The lock count must be zero for the page to be unlocked. This means that if the handle is locked 5 times, it has to be unlocked 5 times. Virtual devices must not leave handles locked when not needed.

Uses

EAX

See Also

_PageLock


_GetSetPageOutCount
include vmm.inc

VMMcall _GetSetPageOutCount, <NewCount, flags>

The _GetSetPageOutCount service either sets or returns the page out count.

This service is for exclusive use by the virtual pageswap device.

Parameter	Description

NewCount	Specifies the new page out count. This parameter is used only if the flag parameter is not set to the GSPOC_F_Get value.

flags	Specifies the operation flags. This parameter can be the following value:

Value	Meaning

GSPOC_F_Get	Returns the current value of the page out count; the NewCount parameter is ignored. If this value is not given, the service sets the value of the page out count to NewCount.

All other values are reserved.

Returns

The EAX register contains the page out count if the GSPOC_F_Get value is given. Otherwise, this service has no return value.

Comments

This service allows the virtual pageswap device to manipulate a memory manager parameter associated with demand paging. This parameter is the page out ahead count. Whenever a page is paged out to satisfy a page in, the system pages out an additional PageOutCount-1 pages and puts the pages on the free list (if possible).

Uses

EAX

See Also

_PageOutDirtyPages


_MMGR_Toggle_HMA
include vmm.inc

VMMcall _MMGR_Toggle_HMA, <VM, flags>

cmp     flags, MMGRHMAQuerry

jne     did_toggle

mov     [HMAState], eax     ; 0 if disabled, 1 if enabled

did_toggle:

or      eax, eax           ; nonzero if enabled/disabled, zero if error

jz      error

The _MMGR_Toggle_HMA service enables or disables the high memory area (HMA). The V86MMGR XMS device uses this service to control the state of the HMA for a specified virtual machine and to notify the instance data manager that the state is changing.

This service is for exclusive use by the V86MMGR XMS device.

Parameter	Description

VM	Specifies a handle identifying the virtual machine.

flags	Specifies the operation flags. It can be one of the following values:

Value	Meaning

MMGRHMAPhysical	Specifies whether the service maps physical pages 100h through 10Fh into the HMA or expects the virtual device to map some other physical pages into the area. The value is used only if the MMGRHMAEnable value is also given.

MMGRHMAEnable	Enables the HMA, allowing addresses greater than 1 megabyte to access pages 100h through 10Fh. If the MMGRHMAPhysical value is given, the service maps physical pages 100h through 10Fh into the linear pages 100h through 10Fh for the virtual machine, enabling the global HMA for this virtual machine and which all virtual machines share.

If the MMGRHMAPhysical value is not given, the service marks the linear pages 100h through 10Fh as not present system pages. To prevent a system crash when these pages are accessed, the virtual device must provide its own physical pages to map into these linear pages. This effectively creates a local HMA that is specific to the given virtual machine.

MMGRHMADisable	Disables the HMA, causing addresses greater than 1 megabyte to be wrapped back to addresses in pages 0 through 0Fh.

MMGRHMAQuerry	Returns the current state of the HMA for the virtual machine.

The MMGRHMAEnable, MMGRHMADisable, MMGRHMAQuerry values are mutually exclusive.

All other values are reserved.

Returns

If MMGRHMAEnable or MMGRHMADisable are given, the EAX register contains a nonzero if the service is successful. Otherwise, EAX contains zero to indicate an error.

If the MMGRHMAQuerry value is given, the EAX register contains a nonzero value if the HMA is enabled and zero if the HMA is disabled.

Comments

This service can fail if the MMGRHMAEnable and MMGRHMAPhysical values are given but the system is already using the physical pages 100h through 10Fh for some other purpose.

A virtual device must not call this service unless it has already used the _Assign_Device_V86_Pages service to assign the pages 100h through 10Fh to itself. For this reason, this service is intended to be used by one and only one virtual device.

When the system creates a virtual machine, it disables the HMA and causes the virtual machine to operate like an 8086 processor. To override this default, the virtual device responsible for the HMA must enable the HMA while processing the VM_Critical_Init message.

Virtual devices must not identify instance data in the HMA.

Uses

EAX

See Also

_Assign_Device_V86_Pages, VM_Critical_Init


_PageOutDirtyPages
include vmm.inc

VMMcall _PageOutDirtyPages, <nPages, flags>

mov     [DirtyPages], eax       ; count of dirty pages flushed

The _PageOutDirtyPages service flushes dirty pages. The virtual pageswap device uses this service to prevent a large number of dirty pages from accumulating in the system.

This service is intended for exclusive use by the virtual pageswap device.

Parameter	Description

nPages	Specifies the maximum number of dirty pages to flush.

flags	Specifies the operation flags. This parameter can be a combination of the following values:

Value	Meaning

PagePDPSetBase	Sets the base page number to the current starting point of the dirty-page scan.

PagePDPClearBase	Clears the base page number.

PagePDPQueryDirty	Returns a count of dirty pages without flushing the pages. The service ignores the nPages parameter and all other flags if this value is given.

All other values are reserved.

Returns

The EAX register contains the actual count of dirty pages flushed by the service.

Comments

The virtual pageswap device typically flushes dirty pages in the system as part of a background activity. It uses this service to scan for and flush current page-out candidates. The virtual pageswap device can flush all the dirty pages by specifying a large value for the nPages parameter. The PagePDPSetBase and PagePDPClearBase values let the virtual pageswap device set and clear a variable that causes the scan for page-out candidates to stop at the given point, and return zero to indicate that the entire address space has been scanned.

Uses

EAX

See Also

_PageDiscardPages


_SetLastV86Page
include vmm.inc

VMMcall _SetLastV86Page, <PgNum, flags>

or      eax, eax            ; nonzero if set, zero if error

jz      not_set

The _SetLastV86Page service sets the page number of the last page in V86 memory for the current virtual machine.

This service is intended for exclusive use by the virtual V86 memory manager device, and is only available for Windows version 3.1 or later.

Parameter	Description

PgNum	Specifies the linear page number to set the last V86 page.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the new last page is set. Otherwise, EAX contains zero to indicate an error, such as an invalid page number.

Comments

This service is intended to help the V86MMGR support backfill machines. These machines have unused, unoccupied memory from the end of MS-DOS memory (typically at 512k) up to 640k (page 0A0h). On such machines, it is desirable to fill out (backfill) this unoccupied space so that virtual machines provide memory up to 640k.

Uses

EAX

See Also

_GetLastV86Page


Set_Physical_HMA_Alias
include vmm.inc

mov     esi, Entries        ; points to PTEs for physical HMA alias

VMMcall Set_Physical_HMA_Alias

The Set_Physical_HMA_Alias service defines an HMA alias for pages 100h through 10Fh. This service is for the exclusive use of the XMS driver, a part of the virtual V86MMGR device, and is only available during initialization.

Parameter	Description

Entries	Points to an array of 16 page table entries which define the physical HMA alias.

Returns

This service has no return value.

Comments

This service does not map new pages into the HMA. Instead, the virtual device must call the _MMGR_Toggle_HMA service with the MMGRHMAPhysical value after the calling this service. This service specifies which pages are mapped when the MMGRHMAPhysical value is specified in a call to the _MMGR_Toggle_HMA service.

Uses

EDI, ESI, EAX, ECX, Flags

See Also

_MMGR_Toggle_HMA


_Add_Global_V86_Data_Area
include vmm.inc

VMMcall _Add_Global_V86_Data_Area, <LinAddr, nBytes, flags>

or      eax, eax        ; nonzero if added, zero if error

jz      not_added

The _Add_Global_V86_Data_Area service adds a region to the list of regions available for allocation as global V86 data areas.

This service is only available during initialization, and only for Windows version 3.1 or later.

Parameter	Description

LinAddr	Specifies the linear address of the first byte of the region. This address must be less than 100000h, and must not lie between the first and last V86 page for the specified virtual machine.

nBytes	Specifies the size in bytes of the region.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error such as an invalid region specification.

Comments

This service supports virtual devices, such as the virtual MS-DOS manager and the V86MMGR device, which can manage high memory above the last V86 page. The service lets these devices add available regions which would otherwise go unused. Typically, such regions are nonpage-aligned fragments which cannot be used for normal operations requiring page-aligned memory.

Calls to this service should be made during processing of the Sys_Critical_Init message. Virtual devices should not wait for the Device_Init or Init_Complete messages since most of the allocation of global V86 data areas is done while processing the Device_Init message.

If this service adds a region that is above the last V86 page, virtual devices should not attempt to allocate the region until the Sys_Critical_Init message has been processed.

Uses

EAX

See Also

_Allocate_Global_V86_Data_Area


_Allocate_Global_V86_Data_Area
include vmm.inc

VMMcall _Allocate_Global_V86_Data_Area, <nBytes, flags>

or      eax, eax        ; zero if error

jz      error

mov     [Address], eax  ; ring-0 linear address of block

The _Allocate_Global_V86_Data_Area service allocates a block of memory from the global V86 data area. The block is for exclusive use by the virtual device. Virtual devices use this service to allocate memory for device-specific objects which must be accessible to both the virtual device and software running in the virtual machine.

This service is only available during initialization.

Parameter	Description

nBytes	Specifies the number of bytes to allocate. This parameter should be a multiple of 4096.

flags	Specifies the operation flags. This parameter can be a combination of the following values:

Value	Meaning

GVDAWordAlign	Aligns block on a word boundary. If no alignment value is given, the service aligns the block on a byte boundary.

GVDADWordAlign	Aligns block on a doubleword boundary. If no alignment value is given, the service aligns the block on a byte boundary.

GVDAParaAlign	Aligns block on a paragraph (16-byte) boundary. If no alignment value is given, the service aligns the block on a byte boundary.

GVDAPageAlign	Aligns block on a page (4 kilobyte) boundary. If no alignment value is given, the service aligns the block on a byte boundary.

The GVDAWordAlign, GVDADWordAlign, GVDAParaAlign, and GVDAPageAlign values are mutually exclusive.

GVDAInstance	Creates an instance data block allowing the virtual device to maintain different values in the block for each virtual machine. If this value is not given, the service creates a global block in which the same data is available to all virtual machines.

GVDAZeroInit	Fills the block with zeros. If this value is not given, the initial content of the block is undefined.

GVDAReclaim	Unmaps any physical pages in the block while mapping the system nul page into the block. The service places unmapped physical pages in the free list. This value only applies if the GVDAPageAlign value is also given. If this value is not given, the service ignores any physical pages it unmaps. It is up to the virtual device to reclaim these pages.

The GVDAReclaim and GVDAInstance values are mutually exclusive.

GVDAInquire	Returns the size in bytes of the largest block that satisfies the requested alignment but does not require the first V86 page to be moved. The nBytes parameter is not used if this value is specified.

A virtual device typically uses this value, while processing the Init_Complete message, to allocate portions of the global V86 data area that might otherwise go unused. The GVDAInquire value is only available for Windows version 3.1 or later.

GVDAHighSysCritOK	Informs the service that the virtual device can manage a block that resides in high MS-DOS memory. The service allocates from high MS-DOS memory only if such memory is available (for example, implemented as xMS UMBs) and the virtual device specifies this value. A virtual device can use this value only while processing the Sys_Critical_Init message.

When first allocated, a block in high MS-DOS memory may not be immediately usable since memory supporting the area may not yet have been mapped. The system maps the memory for the area sometime during the Sys_Critical_Init message, but there is no guarantee as to when.

The GVDAHighSysCritOK value is only available for Windows version 3.1 or later.

All other values are reserved.

Returns

The EAX register contains the ring-0 linear address of the block if the service is successful. Otherwise, EAX contains zero to indicate an error such as insufficient memory to satisfy the request.

If GVDAInquire is given, EAX contains the size in bytes of the largest block that satisfies the request, but that does not move the first V86 page. EAX contains zero if all such requests move the first V86 page.

Comments

If this service returns an error, the virtual device should consider this a fatal error and respond accordingly.

The size returned when the GVDAInquire value is given may be less than a reasonable minimum. For instance, if GVDAPageAlign is specified, the return size may be less than 4096. It is up to the virtual device to check for this.

For blocks allocated with GVDAInstance, this service calls automatically calls the _AddInstanceItem service.

The _Allocate_Global_V86_Data_Area service is not available and must not be called if the virtual device has allocated a temporary block using the _Allocate_Temp_V86_Data_Area service. The virtual device must free the block before it can call the _Allocate_Global_V86_Data_Area service.

If GVDAReclaim is not given, the virtual device should reclaim the physical addresses of any unmapped physical pages and map the pages to other addresses. A virtual device reclaims the physical addresses by using the _CopyPageTable service to retrieve the page table entries for the system virtual machine. The virtual device can then use the _PhysIntoV86 service to map the physical pages into the V86 address space.

Uses

EAX

See Also

_CopyPageTable, _PhysIntoV86


_Allocate_Temp_V86_Data_Area
include vmm.inc

VMMcall _Allocate_Temp_V86_Data_Area, <nBytes, flags>

or      eax, eax        ; zero if error

jz      error

mov     [Address], eax  ; address of temporary block

The _Allocate_Temp_V86_Data_Area service allocates a block of memory from the global V86 data area. The block is for exclusive use by the virtual device during system initialization only. A virtual device typically allocates a temporary block to serve as a buffer for calls to MS-DOS or BIOS functions. A virtual device makes such calls using the Simulate_Int service.

This service is only available during initialization.

Parameter	Description

nBytes	Specifies the number of bytes to allocate.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains the ring-0 linear address of the block if the service is successful. Otherwise, EAX contains zero to indicate an error such as insufficient memory to satisfy the request or temporary area already allocated.

Comments

This service always aligns the temporary block on a paragraph boundary and fills the block with zeros.

Virtual devices must free the temporary block as soon as possible. The system provides only one temporary data area, therefore only one temporary block can be allocated at a time. Attempts to allocate a temporary block when it is already allocated will result in an error.

Uses

EAX

See Also

_Free_Temp_V86_Data_Area


_Free_Temp_V86_Data_Area
include vmm.inc

VMMcall _Free_Temp_V86_Data_Area

or      eax, eax        ; nonzero if freed, zero if error

jz      not_freed

The _Free_Temp_V86_Data_Area service frees the temporary block previously allocated using the _Allocate_Temp_V86_Data_Area service.

This service is only available during initialization.

This service has no parameters.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error such as the temporary area not allocated.

Comments

The _Allocate_Global_V86_Data_Area service is not available while a temporary block is allocated. The virtual device must free the block before the _Allocate_Global_V86_Data_Area service can be called.

This service invalidates the address of the temporary block. Attempting to use the address can cause a system crash.

Uses

EAX

See Also

_Allocate_Temp_V86_Data_Area


_MapIntoV86
include vmm.inc

VMMcall _MapIntoV86, <hMem, VM, VMLinPgNum, nPages, PageOff, flags>

or      eax, eax            ; nonzero if pages mapped, zero if error

jz      not_mapped

The _MapIntoV86 service maps one or more pages of a memory block into the V86 address space of the specified virtual machine.

Parameter	Description

hMem	Specifies the handle identifying the memory block to map. This handle must have been previously created using the PageAllocate or PageReAllocate service.

VM	Specifies a handle identifying the virtual machine for which to map the memory.

VMLinPgNum	Specifies the linear page number of a V86 address. The service maps the specified pages to this address. This parameter must be a page number in the range 10h through 10Fh.

nPages	Specifies the number of pages to map.

PageOff	Specifies the offset in pages from the beginning of the memory block to the first page to map.

flags	Specifies the operation flags. This parameter can be the following value:

Value	Meaning

PageDEBUGNulFault	Enables page faults for system nul pages. If the memory block contains system nul pages, a page fault occurs whenever a nul page is accessed. This value only applies when running the debugging version of the Windows virtual machine manager. If this value is not given or the debugging version is not running, no page faults occur.

All other values are reserved.

Returns

The EAX register contains a nonzero value if the map is successful. Otherwise, EAX contains zero to indicate an error such as an invalid memory handle, an invalid virtual machine handle, an illegal map range, a size discrepancy, or insufficient memory for locking.

Comments

A virtual device typically uses this service to map buffers having protected-mode addresses into the V86 address space. This gives software running in the virtual machine a means of passing data to and receiving data from the virtual device.

The service returns an error if the sum of the PageOff and nPages parameters is greater than the size of the memory block.

Although a virtual device can map the same page into multiple addresses in the V86 address space, this is not recommended.

For each mapped page, this service sets the P_USER, P_PRES, and P_WRITE bits but clears the P_DIRTY and P_ACC bits. The service sets the page type to be identical to the page type for the pages at the specified protected-mode linear address. Although the memory block to be mapped can have PG_SYS page type, it is not recommended.

If the virtual pageswap device uses MS-DOS or BIOS functions to write to the hardware, _MapIntoV86 automatically locks the mapped pages and unlocks any previously mapped pages. If the virtual pageswap device writes directly to the hardware, this service neither lock nor unlocks the pages.

If a virtual device no longer needs the mapped region, it should map the system nul page into the V86 address space using the _MapIntoV86 service. A virtual device can retrieve the handle for the system nul page using the _GetNulPageHandle service.

This service accepts V86 page numbers between 10h and the page number returned by the _GetFirstV86Page service. This supports virtual devices that use the _Allocate_Global_V86_Data_Area service. Mapping a region which spans across the first V86 page is not allowed. Mapping pages in this region to other addresses can easily crash the system and should be avoided.

Uses

EAX

See Also

_Allocate_Global_V86_Data_Area, _GetFirstV86Page, _GetNulPageHandle, _LinMapIntoV86


_PhysIntoV86
include vmm.inc

VMMcall _PhysIntoV86, <PhysPage, VM, VMLinPgNum, nPages, flags>

or      eax, eax                ; nonzero if mapped, zero if an error

jz      not_mapped

The _PhysIntoV86 service maps the specified physical pages in the V86 address space. This service is similar to the _MapIntoV86 service, but takes physical page numbers instead of memory handles. Virtual devices use this service to associate physical device memory (such as the video memory) with a particular virtual machine.

Parameter	Description

PhysPage	Specifies the physical page number of the start of the region to map. A physical page number is a physical address shifted right by 12 bits.

VM	Specifies a handle identifying the virtual machine for which the memory is mapped.

VMLinPgNum	Specifies the linear page number of a page in the 1 megabyte V86 address space. This service maps the physical pages starting at the associated given V86 address. This parameter must not specify page number below 10h or above 10Fh.

nPages	Specifies the number of pages to map.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains a nonzero value if the service is successful. Otherwise, EAX contains zero to indicate an error, such as an invalid virtual machine handle or an illegal map range.

Comments

If more than one physical page is specified, this service maps the pages contiguously. If the physical memory is not contiguous, the virtual device must make individual calls for each page.

Virtual devices must not map physical pages that do not contain actual memory, or that belong to some other device.

For each mapped page, this service sets the P_USER, P_PRES, and P_WRITE bits, but clears the P_DIRTY and P_ACC bits. The service sets the page type to be identical to the type for the specified protected-mode linear address. This service sets the page type to PG_SYS.

Uses

EAX

See Also

_MapIntoV86


_TestGlobalV86Mem
include vmm.inc

VMMcall _TestGlobalV86Mem, <VMLinAddr, nBytes, flags>

mov     [Result], eax           ; 0 if local, 1 if global, 2 if mixed,

                                ; 3 if includes instance data region

The _TestGlobalV86Mem service tests whether a V86 address range is global, local, or instanced.

Parameter	Description

VMLinAddr	Specifies the ring-0 linear address of the first byte of the V86 address range. For example, the linear address of the V86 address 02C1h:0FC5h is 3BD5h (02C10h + 0FC5h).

nBytes	Specifies the size in bytes of the V86 address range.

flags	Specifies the operation flags. This parameter must be set to 0.

Returns

The EAX register contains one of the following values:

Value	Meaning

0	Address range either contains local memory, or is not a valid V86 address range.

1	Address range contains global memory.

2	Address range contains both local and global memory.

3	Address range contains global memory, but also includes an instance data region.

Comments

Global V86 memory has addresses that are valid and identical in all virtual machines. Local memory has addresses that are only valid in one virtual machine. Instanced memory has addresses that are valid in all virtual machines, but the content of the memory varies with each virtual machine.

This service may incorrectly report the type of memory in addresses above page 0A0h (in the device adapter area). If this service returns global for memory in this area, it is global. If the service returns local, however, the memory may actually be global. Generally, this region is local.

Operations involving global address ranges typically do not need to be virtualized since the range is valid and addressable in all virtual machines. Operations involving local address ranges may have to be virtualized since it is possible for software, such as an interrupt handler, to use a local address in the wrong virtual machine.

Uses

EAX


Nested Execution Services

Begin_Nest_Exec	Starts a nested execution block

Begin_Nest_V86_Exec	Starts a V86 nested execution block

End_Nest_Exec	Ends a nested execution block

Exec_Int	Executes a software interrupt

Exec_VxD_Int	Executes a software interrupt

Restore_Client_State	Restores the client state

Resume_Exec	Resumes execution of a virtual machine

Save_Client_State	Saves the client state


Begin_Nest_Exec
include vmm.inc

VMMcall Begin_Nest_Exec

The Begin_Nest_Exec service starts a nested execution block. This service is used in conjunction with the End_Nest_Exec service to create a nested execution block in which a virtual device may call the Exec_Int and Resume_Exec services. Virtual devices use these services to call software in the virtual machine.

This service has no parameters.

Returns

The Client_CS and Client_IP registers contain a break point used by nested execution services.

Comments

While in a nested execution block, a virtual device may call the Exec_Int and Resume_Exec services any number of times.

If one of these calls changes the virtual machine registers, these changes are also made to the client state. Before creating the nested execution block, a virtual device should save the client state by using the Save_Client_State service. After ending the nested execution block, a virtual device should restore the client state by using the Restore_Client_State service.

This service forces the virtual machine into protected-mode execution if there is a protected-mode application running in the current virtual machine. Otherwise, the virtual machine remains in V86 mode. The End_Nest_Exec service restores the virtual machine to its mode prior to the call to Begin_Nest_Exec.

If the execution mode changes to protected mode, this service automatically switches the virtual machine to the locked protected-mode stack and End_Nest_Exec switches it back. This allows most devices to change execution modes without worrying about demand paging issues.

Example

The following example shows a nested call to the MS-DOS function Get Version (Interrupt 21h, Function 30h):

VMMcall Begin_Nest_Exec             ; Start nested execution

mov     [ebp.Client_AH], 30h        ; 30h = Get MS-DOS Version #

mov     eax, 21h                    ; Execute an Int 21h in the

VMMcall Exec_Int                    ; current VM to call DOS

VMMcall End_Nest_Exec               ; End of nested exec calls

This example copies the MS-DOS version to the Client_AH and Client_AL registers.

Uses

Client_CS, Client_IP, Flags

See Also

Begin_Nest_V86_Exec, End_Nest_Exec, Exec_Int, Restore_Client_State, Resume_Exec, Save_Client_State, Set_PM_Exec_Mode, Set_V86_Exec_Mode


Begin_Nest_V86_Exec
include vmm.inc

VMMcall Begin_Nest_V86_Exec

The Begin_Nest_V86_Exec service sets the current virtual machine to V86 mode and prepares the virtual machine for nested execution. This service is used in conjunction with the End_Nest_Exec service to create a nested execution block in which a virtual device may call the Exec_Int and Resume_Exec services. Virtual devices use these services to call software in the virtual machine.

This service has no parameters.

Returns

The Client_CS and Client_IP registers contain a break point used by nested execution services.

Comments

When in a nested execution block, a virtual device may call the Exec_Int and Resume_Exec services any number of times.

This service should only be used by virtual devices that convert protected-mode calls into V86 calls. For example, the virtual MS-DOS manager uses this service to map calls to MS-DOS functions (Interrupt 21h) issued by protected-mode programs into calls to MS-DOS functions in V86 mode.

This service saves the current execution mode of the virtual machine and End_Nest_Exec restores the mode.

Uses

Client_CS, Client_IP, Flags

See Also

Begin_Nest_Exec, End_Nest_Exec


End_Nest_Exec
include vmm.inc

VMMcall End_Nest_Exec

The End_Nest_Exec service ends a nested execution block. This service is used in conjunction with the Begin_Nest_Exec or Begin_Nest_V86_Exec service to create a nested execution block in which virtual devices may call the Exec_Int and Resume_Exec services.

This service has no parameters.

Returns

The Client_CS and Client_IP registers contain the original values saved by when the nested execution block was created.

Comments

A virtual device must end all nested execution blocks before returning to the virtual machine manager.

This service restores the execution mode to the mode prior to the start of the nested execution block. It also restores the Client_CS and Client_IP registers, but does not restore any other client registers. A virtual device should save and restore these registers using the Save_Client_State and Restore_Client_State macros.

Uses

Client_CS, Client_IP, Flags

See Also

Begin_Nest_Exec, Begin_Nest_V86_Exec, Restore_Client_State, Save_Client_State


Exec_Int
include vmm.inc

mov     eax, Interrupt      ; number of interrupt to execute

VMMcall Exec_Int

The Exec_Int service simulates the specified interrupt and resumes execution of the virtual machine. This service may only be called in a nested execution block created using the Begin_Nest_Exec or Begin_Nest_V86_Exec service.

Parameter	Description

Interrupt	Specifies the number of the interrupt to simulate.

Returns

This service has no return value.

Comments

When in a nested execution block, this service can be called any number of times.

This service is comparable to combining the Simulate_Int and Resume_Exec services.

Uses

Flags

See Also

Begin_Nest_Exec, Begin_Nest_V86_Exec, Resume_Exec, Simulate_Int


Exec_VxD_Int
include vmm.inc

push    dword ptr Interrupt     ; number of interrupt to execute

VMMcall Exec_VxD_Int

The Exec_VxD_Int service executes the specified software interrupt. Virtual devices uses this service to call MS-DOS or BIOS functions outside the context of a nested execution block.

Parameter	Description

Interrupt	Specifies the number of the interrupt to execute.

Returns

One or more registers may contain return values depending the function of the specified interrupt.

Comments

Before calling this service, a virtual device must set registers to values that are appropriate for the specified software interrupt. This service supports all MS-DOS and BIOS functions that are supported in protected mode programs.

This service does not change the client registers and flags, so there is no need for the virtual device to save and restore the client register structure. This service also pops the interrupt number from the stack.

Example

The following examples calls the MS-DOS function Get Version (Interrupt 21h, Function 30h):

mov     ax, 3000h

push    dword ptr 21h

VMMcall Exec_VxD_Int

mov     [Major], al     ; major MS-DOS version

mov     [Minor], al     ; minor MS-DOS version

See Also

VxDint


Restore_Client_State
include vmm.inc

mov     esi, Buffer        ; points to buffer containing saved state

VMMcall Restore_Client_State

The Restore_Client_State service restores a virtual machine execution state that was saved using the Save_Client_State service.

Parameter	Description

Buffer	Points to the buffer containing the client state previously saved using the Save_Client_State service.

Returns

This service has no return value.

Comments

This service can have the following side effects:

Changes the execution mode if the state being restored is in a different execution mode from the current one.

May change the state of the current virtual machine's interrupt flag and cause the system to call event callback procedures that were previously scheduled using the Call_When_VM_Ints_Enabled and Call_Priority_VM_Event services.

Uses

Flags

See Also

Call_When_VM_Ints_Enabled, Call_Priority_VM_Event, Save_Client_State


Resume_Exec
include vmm.inc

VMMcall Resume_Exec

The Resume_Exec service immediately executes the current virtual machine. This service may only be called in a nested execution block created using the Begin_Nest_Exec or Begin_Nest_V86_Exec service.

This service has no parameters.

Returns

This service has no return value.

Comments

This service can be use any number of times in a nested execution block.

This service returns when the virtual machine returns to the same point it was at when Begin_Nest_Exec was called.

Uses

Flags

See Also

Begin_Nest_Exec, Begin_Nest_V86_Exec


Save_Client_State
include vmm.inc

mov     edi, Buffer         ; points to the buffer to receive client state

VMMcall Save_Client_State

The Save_Client_State service copies the contents of the current virtual machine's Client_Reg_Struc structure to the specified buffer. The saved state can later be restored by calling the Restore_Client_State service.

Parameter	Description

Buffer	Points to the buffer to receive the client state. The buffer must have the same size as a Client_Reg_Struc structure.

Returns

This service has no return value.

Comments

Virtual devices typically use this service to save client registers prior to creating a nested execution block with the Begin_Nest_Exec or Begin_Nest_V86_Exec service.

Never attempt to restore the client state by directly copying saved register values back to the Client_Reg_Struc structure; this will almost certainly cause the virtual machine manager to crash.

Uses

Flags

See Also

Restore_Client_State


Primary Scheduler Services

Adjust_Exec_Priority	Raises or lowers priority

Begin_Critical_Section	Claims a critical section

Call_When_Idle	Installs system-idle callback procedure

Call_When_Not_Critical	Installs a critical-section callback

Call_When_Task_Switched	Installs a task-switched callback

Claim_Critical_Section	Claims a critical section

Close_VM	Closes a virtual machine

Create_Semaphore	Creates a semaphore

Destroy_Semaphore	Destroys a semaphore

End_Crit_And_Suspend	Releases critical section and suspends VM

End_Critical_Section	Releases the critical section

Get_Crit_Section_Status	Gets critical section status

Get_Crit_Status_No_Block	Returns claim count and owner

No_Fail_Resume_VM	Resume execution without failing

Nuke_VM	Closes a virtual machine

Release_Critical_Section	Releases the critical section

Resume_VM	Resumes a virtual machine

Signal_Semaphore	Unblocks a waiting virtual machine

Suspend_VM	Suspends a virtual machine

Wait_Semaphore	Waits until semaphore is signaled


Adjust_Exec_Priority
include vmm.inc

mov     eax, PriorityBoost    ; signed integer specifying priority boost

mov     ebx, VM               ; VM handle

VMMcall Adjust_Exec_Priority

The Adjust_Exec_Priority service raises or lowers the execution priority of the specified virtual machine. The service adds the specified boost to the virtual machine's current execution priority.

Parameter	Description

PriorityBoost	Specifies a positive or negative priority boost for the virtual machine. This parameter must be a value such that when added to the current execution priority, the result is within the range Reserved_Low_Boost to Reserved_High_Boost.

The following lists some common priority boost values:

Value	Meaning

Reserved_Low_Boost	Reserved for use by system.

Cur_Run_VM_Boost	The time-slice scheduler uses this value to force a virtual machine to run for its allotted time-slice.

Low_Pri_Device_Boost	Virtual devices use this value for events that need timely processing but are not time critical.

High_Pri_Device_Boost	Virtual devices use this value for events that need timely processing but should not circumvent operations that have a critical section boost.

Critical_Section_Boost	The system uses this value for virtual machines specified in a call to the Begin_Critical_Section service.

Time_Critical_Boost	Virtual devices use this value for events that must be processed even when another virtual machine is in a critical section. For example, VPICD uses this when simulating hardware interrupts.

Reserved_High_Boost	Reserved for use by system.

VM	Specifies the handle identifying the virtual machine.

Returns

This service has no return value.

Comments

Since the nonsuspended virtual machine with the highest execution priority is always the current virtual machine, this service causes a task switch under two circumstances:

1	The execution priority of the current virtual machine is lowered (EAX is negative), and there is another virtual machine with a higher priority that is not suspended.

2	The execution of a nonsuspended virtual machine which is not the current virtual machine is raised (EAX is positive) higher than the current virtual machine's execution priority.

Even if the current virtual machine is in a critical section, a task switch will still occur if the priority of another nonsuspended virtual machine is raised higher than the current virtual machine's priority. However, this will only occur when a virtual machine is given a time-critical boost, for example, to simulate a hardware interrupt.

It is often more convenient to call the Call_Priority_VM_Event service than to call this service directly.

Uses

Flags

See Also

Begin_Critical_Section, Call_Priority_VM_Event


Begin_Critical_Section
include vmm.inc

mov     ecx, Flags              ; flags for servicing interrupts

VMMcall Begin_Critical_Section

The Begin_Critical_Section service causes the current virtual machine to enter a critical section. Only one virtual machine can own the critical section at a time. If a virtual machine calls this service while another virtual machine owns the critical section, the calling virtual machine will block until the critical section is released.

Parameter	Description

Flags	Specifies actions to take when interrupts occur while the virtual machine is blocked waiting for the critical section. This parameter can be a combination of the following values:

Value	Meaning

Block_Svc_Ints	Service interrupts in the virtual machine even if the virtual machine is blocked.

Block_Svc_If_Ints_Locked	Service interrupts in the virtual machine even if the virtual machine is blocked and the VMStat_V86IntsLocked flag is set.

Block_Enable_Ints	Service interrupts in the virtual machine even if the virtual machine does not currently have interrupts enabled. This forces interrupts to be enabled. This value is only relevant if either Block_Svc_Ints or Block_Svc_If_Ints_Locked is set.

The Block_Poll value is reserved and must not be used with this service.

Returns

This service has no return value.

Comments

The system maintains a count of claims for critical sections and releases the critical section only when an equal number of Begin_Critical_Section End_Critical_Section services have been called.

When the critical section is first claimed, the system boosts the execution priority of the current virtual machine by the Critical_Section_Boost value (as described for the Adjust_Exec_Priority service). While a virtual machine is in a critical section, the system will switch to another task only if the virtual machine blocks on a semaphore or the other task has a time-critical operation, such as simulating hardware interrupts.

Uses

Flags

See Also

Adjust_Exec_Priority, End_Critical_Section


Call_When_Idle
include vmm.inc

mov     esi, OFFSET32 IdleCallback      ; points to callback procedure

VMMcall Call_When_Idle

jc      error                       ; carry set if callback not installed

The Call_When_Idle service installs a system-idle callback procedure. The system calls this procedure whenever the Windows kernel signals that Windows is idle and all other virtual machines are also idle. Virtual devices typically use this service to perform background operations. For example, the pageswap device uses this service to asynchronously write dirty pages to the backing store.

Parameter	Description

IdleCallback	Points to the callback procedure to install. See the Comments section for more information about the procedure.

Returns

The carry flag is clear if the callback procedure is installed. Otherwise, the carry flag is set.

Comments

Virtual devices can install any number of idle callback procedures. The system calls each one, in the order installed, until one of the procedures clears the carry flag.

The system calls each callback procedure as follows:

mov     ebx, SysVM          ; system VM handle

mov     ebp, OFFSET32 crs   ; points to a Client_Reg_Struc structure

call    [IdleCallback]

jc      pass_to_next        ; if carry set, call the next idle callback

The SysVM parameter specifies a handle identifying the system virtual machine and the csr parameters points to a Client_Reg_Struc structure containing the registers of the system virtual machine.

The callback procedure can carry out any operation and can modify EAX, EBX, ECX, EDX, ESI, EDI, and Flags. If the operation takes a significant amount of time, the procedure should clear the carry flag before returning to prevent other callbacks from being called. Otherwise,  the procedure should set the carry flag and return.

Uses

Flags

See Also

Call_When_Not_Critical, Call_When_Task_Switched


Call_When_Not_Critical
include vmm.inc

mov     esi, CritSecCallback    ; points to callback procedure

mov     edx, RefData            ; points to data to pass to callback

VMMcall Call_When_Not_Critical

The Call_When_Not_Critical service installs a critical-section callback procedure. The system calls this procedure whenever a virtual device releases the critical section.

Parameter	Description

CritSecCallback	Points to the callback procedure to install. See the Comments section for more information about the procedure.

RefData	Points to reference data to pass to the callback procedure.

Returns

This service has no return value.

Comments

The system does not execute the callback until the current virtual machine's execution priority is less than the Critical_Section_Boost value even if the current virtual machine is not in a critical section. This allows a virtual device to release the critical section and process any simulated interrupts before the system calls the callback procedure.

Virtual devices can install any number of callback procedures, but the system calls only the most recent procedure on the list when the critical section is released. The system removes the callback procedure from the list as it calls the procedure.

The system calls the callback procedure as follows:

mov     ebx, VM                 ; current VM handle

mov     edx, OFFSET32 RefData   ; points to reference data

mov     ebp, OFFSET32 crs       ; points to a Client_Reg_Struc structure

call    [CritSecCallback]

The VM parameter specifies a handle identifying the current virtual machine, RefData points to reference data from the virtual device that installed the callback, and the csr parameter points to a Client_Reg_Struc structure containing the registers of the current virtual machine.

The callback procedure can carry out any operation and can modify EAX, EBX, ECX, EDX, ESI, EDI, and Flags.

It is more convenient to use the Call_Priority_VM_Event service than to call this service directly.

Uses

Flags

See Also

Call_When_Idle, Call_When_Task_Switched


Call_When_Task_Switched
include vmm.inc

mov     esi, TaskSwitchCallback    ; points to callback procedure

VMMcall Call_When_Task_Switched

The Call_When_Task_Switched service installs a task-switched callback procedure. The system calls this procedure whenever it carries out a task switch. This service should be used sparingly and the callback procedure should be optimized for speed.

Parameter	Description

TaskSwitchCallback	Points to the callback procedure to install. See the Comments section for more information about the procedure.

Returns

This service has no return value.

Comments

Some virtual devices must save the state of a hardware device every time a task switch occurs and restore the hardware state for the virtual machine that is about to be run. However, virtual machine events can often be used in place of using this service.

Virtual devices can install any number of callback procedures. The system calls each one in the order installed, until all procedures have been called.

The system calls the callback procedure as follows:

mov     eax, OldVM              ; previous VM handle

mov     ebx, VM                 ; current VM handle

call    [CritSecCallback]

The OldVM parameter specifies a handle identifying the previous virtual machine (just prior to the task switch), and VM specifies a handle identifying the current virtual machine.

The callback procedure can carry out any operation and can modify EAX, EBX, ECX, EDX, ESI, EDI, and Flags.

Uses

Flags

See Also

Call_When_Idle, Call_When_Not_Critical


Claim_Critical_Section
include vmm.inc

mov     eax, Claims             ; number of times to claim critical section

mov     ecx, Flags              ; flags for servicing interrupts

VMMcall Claim_Critical_Section

The Claim_Critical_Section service increments the claim count by the specified value. It has the same effect as calling the Begin_Critical_Section service repeatedly.

Parameter	Description

Claims	Specifies the number of times to claim the critical section. Zero is a valid number, but is ignored.

Flags	Specifies actions to take when interrupts occur while the virtual machine is blocked waiting for the critical section. This parameter can be a combination of the following values:

Value	Meaning

Block_Svc_Ints	Service interrupts in the virtual machine even if the virtual machine is blocked.

Block_Svc_If_Ints_Locked	Service interrupts in the virtual machine even if the virtual machine is blocked and the VMStat_V86IntsLocked flag is set.

Block_Enable_Ints	Service interrupts in the virtual machine even if the virtual machine does not currently have interrupts enabled. This forces interrupts to be enabled. This value is only relevant if either Block_Svc_Ints or Block_Svc_If_Ints_Locked is set.

The Block_Poll value is reserved and must not be used with this service.

Returns

This service has no return value.

Uses

Flags

See Also

Adjust_Exec_Priority, Begin_Critical_Section, End_Critical_Section


Close_VM
include vmm.inc

mov     eax, TimeOut    ; milliseconds to wait before failing close

mov     ebx, VM         ; handle of VM to close

mov     ecx, Flags      ; action to take

VMMcall Close_VM

The Close_VM service attempts to close the virtual machine, allowing all virtual devices an opportunity to clean up before the virtual machine terminates.

This service is only available in Windows version 3.1 and later.

Parameter	Description

TimeOut	Specifies the number of milliseconds the service must wait before calling the NukeVM service to force the virtual machine to close.

VM	Specifies a handle identifying the virtual machine to close.

Flags	Specifies whether to return to the caller while closing the virtual machine. This parameter can be a combination of the following values:

Value	Meaning

CVF_Continue_Exec	Return to the virtual machine after scheduling the closing event even if the virtual machine is being closed.

All other values are reserved.

Returns

This service has no return value.

Comments

Whenever possible, a virtual device should use this service instead of the the Nuke_VM or Crash_Cur_VM service.

Uses

Flags


Create_Semaphore
include vmm.inc

mov     ecx, TokenCount     ; initial token count

VMMcall Create_Semaphore

jc      error               ; carry set if semaphore not created

mov     [Semaphore], eax    ; semaphore handle

The Create_Semaphore service allocates memory for and initializes a new semaphore.

Parameter	Description

TokenCount	Specifies the initial count of tokens.

Returns

The carry flag is clear and the EAX register contains the semaphore handle if the function is successful. Otherwise, the carry flag is set to indicate an error.

Uses

EAX, Flags

See Also

Destroy_Semaphore, Signal_Semaphore, Wait_Semaphore


Destroy_Semaphore
include vmm.inc

mov     eax, Semaphore      ; semaphore handle

VMMcall Destroy_Semaphore

The Destroy_Semaphore service destroys the specified semaphore.

Parameter	Description

Semaphore	Specifies the handle of the semaphore to delete.

Returns

This service has no return value.

Uses

Flags

See Also

Create_Semaphore


End_Crit_And_Suspend
include vmm.inc

VMMcall End_Crit_And_Suspend

jc      not_released            ; carry set if critical section not released

The End_Crit_And_Suspend service releases the critical section and immediately suspends the current virtual machine. Virtual devices use this service to block a virtual machine until another virtual machine can process an event.

This service has no parameters.

Returns

The carry flag is clear if this service is successful. Otherwise, the carry flag is set to indicate an error.

Comments

This service releases the critical section only if the virtual machine has claimed the section once. This service returns an error if the system could not suspend the virtual machine, or could not release the critical section because the claim count was not 1. In such cases, the service does not decrement the claim count and the critical section is not released.

Example

The following example uses this service to display a dialog box in the system virtual machine. The Show_Dialog_Box procedure enters a critical section to prevent the Call_Priority_VM_Event service from switching to the system virtual machine immediately. It then calls End_Crit_And_Suspend which blocks the current virtual machine. The Show_Dialog_Event procedure runs in the system virtual machine and actually displays the dialog box. When it is finished it resumes the virtual machine that called Show_Dialog_Box by calling the Resume_VM service.

Show_Dialog_Box:

    VMMcall Get_Crit_Section_Status

    jc      Cant_Do_It                  ; critical section already claimed

    VMMcall Begin_Critical_Section

    mov     eax, Low_Pri_Device_Boost

    VMMcall Get_System_VM_Handle

    mov     ecx, 11b

    mov     edx, OFFSET32 Dialog_Box_Data_Strucure

    mov     esi, OFFSET32 Show_Dialog_Event

    VMMcall Call_Priority_VM_Event

    VMMcall End_Crit_And_Suspend

    jc      Did_Not_Work

    ; When End_Crit_And_Suspend returns the dialog box

    ; will have been displayed

Show_Dialog_Event:

    ; Call Windows to display the dialog box

    mov     ebx, [Suspended_VM_Id]

    VMMcall Resume_VM

    jc      Error

    ret

Uses

Flags

See Also

End_Critical_Section, Resume_VM, Suspend_VM


End_Critical_Section
include vmm.inc

VMMcall End_Critical_Section

The End_Critical_Section service releases the critical section if the current virtual machine owns the section and the claim count is zero.

This service has no parameters.

Returns

This service has no return value.

Comments

This service decrements the claim count and releases the critical section if the new count is zero. Since releasing the critical section lowers the execution priority of the current virtual machine, this service causes a task switch if a nonsuspended virtual machine has higher priority.

Uses

Flags

See Also

Begin_Critical_Section, End_Crit_And_Suspend


Get_Crit_Section_Status
include vmm.inc

VMMcall Get_Crit_Section_Status

mov     [VM], ebx           ; VM handle of owner

mov     [Claims], ecx       ; # of times critical section claimed

jc      high_priority       ; priority is Critical_Section_Boost or higher

The Get_Crit_Section_Status service returns the claim count and owner of the critical section.

This service has no parameters.

Returns

The ECX register contains the critical section claim count, and the EBX register contains the handle identifying the virtual machine owning the critical section. If the ECX register is 0, the EBX register contains the handle of the current virtual machine.

The carry flag is set if the current virtual machine has an execution priority greater than or equal to Critical_Section_Boost, such as during a hardware interrupt simulation.

Comments

Windows 3.1 sometimes delays releasing the critical section until events are processed. This service causes the system to complete any delayed releases before the service returns the status. This may cause a task switch if another virtual machine has a delayed release.

If a virtual device must ensure that it owns the critical section to successfully complete an operation, it should call this service to make sure that the critical section status is up to date.

This is not an asynchronous service; it must not be called at interrupt time.

Uses

Flags

See Also

Get_Crit_Status_No_Block


Get_Crit_Status_No_Block
include vmm.inc

VMMcall Get_Crit_Status_No_Block

mov     [VM], ebx           ; VM handle of owner

mov     [Claims], ecx       ; # of times critical section claimed

jc      high_priority       ; priority is Critical_Section_Boost or higher

(Version 3.1 only)

The Get_Crit_Status_No_Block service returns the claim count and handle of the owner of the critical section. Unlike the Get_Crit_Section_Status service, this service returns immediately (without blocking) even if a delayed request to release the critical section is pending.

This service has no parameters.

Returns

The ECX register contains the critical section claim count, and the EBX register contains the handle identifying the virtual machine owning the critical section. If the ECX register is 0, the EBX register contains the handle of the current virtual machine.

The carry flag is set if the current virtual machine has an execution priority greater than or equal to Critical_Section_Boost, such as during a hardware interrupt simulation.

Comments

In some cases, this service may indicate that the critical section is currently owned even when it will be released before returning to the virtual machine.

This is an asynchronous service; it may be called at interrupt time.

Uses

Flags

See Also

End_Critical_Section, Get_Crit_Section_Status


No_Fail_Resume_VM
include vmm.inc

mov     ebx, VM             ; VM handle

VMMcall No_Fail_Resume_VM

The No_Fail_Resume_VM service resumes the execution of a virtual machine previously suspended by the Suspend_VM service. Unlike the Resume_VM service, this service never returns an error.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to resume.

Returns

This service has no return value.

Comments

This service decrements the suspend count, and places the virtual machine in the ready-processes queue if the new count is zero. The system carries out a task switch to the resumed virtual machine if the virtual machine has a higher priority than the current virtual machine.

If the virtual machine cannot be resumed for some reason, the system notifies the user of the problem and handles the error automatically, resuming the virtual machine when there is sufficient memory available.

Uses

Flags

See Also

Resume_VM, Suspend_VM


Nuke_VM
include vmm.inc

mov     ebx, VM         ; VM handle

VMMcall Nuke_VM

The Nuke_VM service closes a virtual machine that has not yet terminated.

Parameter	Description

VM	Specifies the handle identifying the virtual machine to destroy. If this parameter specifies the system virtual machine, the service closes Windows and returns to MS-DOS.

Returns

The service has no return value. If the VM parameter specifies the current or system virtual machine, this service never returns.

Comments

The virtual shell device typically calls this service to close a virtual machine whenever the user chooses the Terminate button from the virtual machine's Settings dialog box.

This service should be used with caution.

Uses

ECX, EDX, Flags

See Also

Close_VM, Crash_Cur_VM


Release_Critical_Section
include vmm.inc

mov     ecx, Claims         ; number of times to release critical section

VMMcall Release_Critical_Section

The Release_Critical_Section service decrements the claim count by the specified value. It has the same effect as calling the End_Critical_Section section repeatedly.

Parameter	Description

Claims	Specifies the number of times to release ownership of critical section. Zero is a valid number, but is ignored.

Returns

This service has no return value.

Uses

Flags

See Also

Claim_Critical_Section, End_Critical_Section


Resume_VM
include vmm.inc

mov     ebx, VM         ; VM handle

VMMcall Resume_VM

jc      not_resumed     ; carry set if virtual machine not resumed

The Resume_VM service resumes the execution of a virtual machine previously suspended by the Suspend_VM service.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to resume.

Returns

The carry flag is clear if the suspend count is zero and the virtual machine is in the ready-processes queue. The carry flag is clear to indicate an error.

Comments

This service decrements the suspend count and places the virtual machine in the ready-processes queue if the new count is zero. The system carries out a task switch to the resumed virtual machine if the virtual machine has a higher priority than the current virtual machine.

An error can occur if a virtual device cannot lock the memory handles for the specified virtual machine. The system notifies every virtual device of the request to resume a virtual machine, and any virtual device can deny the request. In such cases, this service returns with the carry flag set and the virtual machine remains suspended with a suspend count of 1.

Uses

Flags

See Also

No_Fail_Resume_VM, Suspend_VM


Signal_Semaphore
include vmm.inc

mov     eax, Semaphore      ; semaphore handle

VMMcall Signal_Semaphore

The Signal_Semaphore service unblocks the virtual machine (if any) waiting on the specified semaphore. The unblocked virtual machine checks the state of the semaphore's unblock count and resumes execution if the count is zero or greater.

Parameter	Description

Semaphore	Specifies a handle identifying the semaphore to signal.

Returns

This service has no return value.

Comments

This service increments the semaphore's token count. If the incremented token count is less than or equal to zero, the service increments the semaphore's unblock count and schedules a wake up event for the virtual machine blocked on the semaphore. Otherwise, this service returns immediately.

Uses

Flags

See Also

Create_Semaphore, Wait_Semaphore


Suspend_VM
include vmm.inc

mov     ebx, VM         ; VM handle

VMMcall Suspend_VM

jc      not_suspended   ; carry set if virtual machine not suspended

The Suspend_VM service suspends the execution of a specified virtual machine. This service fails if the specified virtual machine either owns the critical section, or is the system virtual machine.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to suspend.

Returns

The carry flag is clear if the virtual machine is suspended. The carry flag is set to indicate an error.

Comments

An error occurs if the virtual machine is in a critical section or is the VM parameter specifies the system virtual machine.

This service increments the suspend count for the virtual machine. If the virtual machine was not already suspended, the system notifies virtual devices of the suspension by sending a VM_Suspend command to the control procedure for each virtual device. A virtual device must not refuse to suspend a virtual machine. If a virtual machine remains suspended, subsequent calls to Suspend_VM do not cause the VM_Suspend notification.

When a virtual machine is suspended, the system sets the VMStat_Suspended bit in the CB_VM_Status field of the virtual machine's control block. Although virtual devices may examine and modify the contents of the control block of a virtual machine, the virtual devices must not examine or modify any memory owned by a suspended virtual machine unless the virtual device previously locked that memory.

Uses

Flags

See Also

No_Fail_Resume_VM, Resume_VM


Wait_Semaphore
include vmm.inc

mov     eax, Semaphore      ; semaphore handle

mov     ecx, Flags          ; flags for servicing interrupts

VMMcall Wait_Semaphore

The Wait_Semaphore service blocks the current virtual machine until the semaphore is signaled using the Signal_Semaphore service.

Parameter	Description

Semaphore	Specifies a handle identifying the semaphore on which to wait.

Flags	Specifies actions to take when interrupts occur while the virtual machine is blocked waiting for the semaphore. This parameter can be a combination of the following values:

Value	Meaning

Block_Svc_Ints	Service interrupts in the virtual machine even if the virtual machine is blocked.

Block_Svc_If_Ints_Locked	Service interrupts in the virtual machine even if the virtual machine is blocked and the VMStat_V86IntsLocked flag is set.

Block_Enable_Ints	Service interrupts in the virtual machine even if the virtual machine does not currently have interrupts enabled. This forces interrupts to be enabled. This value is only relevant if either Block_Svc_Ints or Block_Svc_If_Ints_Locked is set.

Block_Poll	Do not switch away from the blocked virtual machine unless another virtual machine has higher priority.

Returns

This service has no return value.

Comments

This service blocks if the semaphore's unblock count is zero and the token count is zero or less. Otherwise, it decrements the token count and returns immediately. If the unblock count is not zero (meaning the Signal_Semaphore service has been called), Wait_Semaphore decrements the unblock count and returns immediately.

Uses

Flags

See Also

Create_Semaphore, Signal_Semaphore


Protected-Mode Execution Services

Allocate_PM_App_CB_Area	Allocates application control block

Begin_Use_Locked_PM_Stack	Locks protected-mode stack

End_Use_Locked_PM_Stack	Unlocks the protected-mode stack

Get_Cur_PM_App_CB	Returns application control block

Set_PM_Exec_Mode	Sets protected-mode execution

Set_V86_Exec_Mode	Set V86 mode execution


Allocate_PM_App_CB_Area
include vmm.inc

mov     ecx, Size           ; number of bytes to reserve

VMMcall Allocate_PM_App_CB_Area

mov     [acb], eax          ; offset of application control block

The Allocate_PM_App_CB_Area service allocates space in the control block of the current virtual machine for an protected-mode application control block.

This service is only available during initialization.

Parameter	Description

Size	Specifies the number of bytes to reserve for the control block.

Returns

The EAX register contains the offset from the beginning of the virtual machine control block to the protected-mode application control block.

Uses

EAX

See Also

Application_Control_Block


Begin_Use_Locked_PM_Stack
include vmm.inc

VMMcall Begin_Use_Locked_PM_Stack

The Begin_Use_Locked_PM_Stack service locks the protected-mode stack, preventing demand paging of the stack. Virtual devices use this service to ensure that a protected-mode application runs on a stack that will not be demand paged.

This service has no parameters.

Returns

The Client_SS and Client_SP registers contain the address of the locked stack if the stack was not already locked. Otherwise, these registers remain unchanged.

Comments

Before calling this service, the virtual device must ensure that the current virtual machine is running in protected mode. This means the VMStat_PM_Exec value must be specified in the CB_VM_Status field of the control block for the virtual machine.

Since most virtual devices rely on the Begin_Nest_Exec service to switch stacks, this service is only useful for virtual devices, such as the virtual PIC device, which explicitly change the execution mode of a virtual machine.

A virtual device can call this service any numbr of times. Only the first call switches stacks; all subsequent calls increment a counter. If a virtual device locks the stack, it must eventually unlock it using the End_Use_Locked_PM_Stack service.

Uses

Flags

See Also

Begin_Nest_Exec, End_Use_Locked_PM_Stack


End_Use_Locked_PM_Stack
include vmm.inc

VMMcall End_Use_Locked_PM_Stack

The End_Use_Locked_PM_Stack service unlocks the protected-mode stack. This service decrements the locked-stack counter and restores the previous stack of the virtual machine if the counter is zero. To unlock the stack, a virtual device must call this service once for each call made to the Begin_Use_Locked_PM_Stack service.

This service has no parameters.

Returns

If locked-stack counter is zero, the Client_SS, Client_SP, and Client_EIP registers contain the original values before the Begin_Use_Locked_PM_Stack service was called. Otherwise, these registers remain unchanged.

Uses

Flags

See Also

Begin_Use_Locked_PM_Stack


Get_Cur_PM_App_CB
include vmm.inc

mov     ebx, VM                 ; handle of VM running protected-mode app

VMMcall Get_Cur_PM_App_CB

mov     [ControlBlock], edi     ; address of application control block

The Get_Cur_PM_App_CB services returns a pointer to the application control block for a protected-mode application.

Parameter	Description

VM	Specifies a handle identifying the virtual machine in which the protected-mode application is running.

Returns

The EDI register contains the address of the application control block.

Uses

EDI

See Also

Application_Control_Block


Set_PM_Exec_Mode
include vmm.inc

VMMcall Set_PM_Exec_Mode

The Set_PM_Exec_Mode service forces the current virtual machine into protected mode. If the current virtual machine is already in protected mode, this service has no effect.

This service has no parameters.

Returns

This service has no return value.

Comments

Whenever possible, a virtual device should use the Begin_Nest_Exec service instead of this service.

Changing the execution mode of a virtual machine does not change the virtual machine's EAX, EBX, ECX, EDX, ESI, EDI, and EBP registers or most flags. The VM flag and IOPL flags change. The DS, ES, FS, GS, SS, ESP, CS, and EIP register are restored to the previous values for V86 mode.

Uses

Flags

See Also

Begin_Nest_Exec, Set_V86_Exec_Mode


Set_V86_Exec_Mode
include vmm.inc

VMMcall Set_V86_Exec_Mode

The Set_V86_Exec_Mode service forces the current virtual machine into V86 mode. If the current virtual machine is already in V86 mode, this service has no effect.

This service has no parameters.

Returns

This service has no return value.

Comments

Changing the execution mode of a virtual machine does not change the virtual machine's EAX, EBX, ECX, EDX, ESI, EDI, and EBP registers or most flags. The VM flag and IOPL flags change. The DS, ES, FS, GS, SS, ESP, CS, and EIP registers are restored to the previous values for V86 mode.

Uses

Flags

See Also

Set_PM_Exec_Mode


VMM Structures

Application_Control_Block	Information about an application

Client_Reg_Struc	Client Registers

Control_Block	Information about a virtual machine

DemandInfoStruc	Demand page information

Exception_Handler_Struc	Defines a ring-0 exception handler

InstDataStruc	Information about an instance data block

IPF_Data	Invalid page fault information


Application_Control_Block
include vmm.inc

mov     esi, OFFSET32 acb

mov     eax, [esi+PMCB_Flags]       ; application flags

mov     eax, [esi+PMCB_Parent]      ; application parent

The application control block contains information about a protected-mode application. Virtual devices can use the following offsets to access information in the control block:

Offset	Description

PMCB_Flags	Specifies the control block flags.

PMCB_Parent	Specifies the parent of the protected-mode application.

See Also

Get_Cur_PM_App_CB, Control_Block


Client_Reg_Struc
include vmm.inc

Client_Reg_Struc   struc

Client_EDI      dd      ?       ; Client's EDI

Client_ESI      dd      ?       ; Client's ESI

Client_EBP      dd      ?       ; Client's EBP

                dd      ?       ; ESP at pushall

Client_EBX      dd      ?       ; Client's EBX

Client_EDX      dd      ?       ; Client's EDX

Client_ECX      dd      ?       ; Client's ECX

Client_EAX      dd      ?       ; Client's EAX

Client_Error    dd      ?       ; Doubleword error code

Client_EIP      dd      ?       ; EIP

Client_CS       dw      ?       ; CS

                dw      ?       ;   (padding)

Client_EFlags   dd      ?       ; EFLAGS

Client_ESP      dd      ?       ; ESP

Client_SS       dw      ?       ; SS

                dw      ?       ;   (padding)

Client_ES       dw      ?       ; ES

                dw      ?       ;   (padding)

Client_DS       dw      ?       ; DS

                dw      ?       ;   (padding)

Client_FS       dw      ?       ; FS

                dw      ?       ;   (padding)

Client_GS       dw      ?       ; GS

                dw      ?       ;   (padding)

Client_Alt_EIP  dd      ?

Client_Alt_CS   dw      ?

                dw      ?

Client_Alt_EFlags  dd   ?

Client_Alt_ESP  dd      ?

Client_Alt_SS   dw      ?

                dw      ?

Client_Alt_ES   dw      ?

                dw      ?

Client_Alt_DS   dw      ?

                dw      ?

Client_Alt_FS   dw      ?

                dw      ?

Client_Alt_GS   dw      ?

                dw      ?

Client_Reg_Struc   ends

The Client_Reg_Struc structure contains the CPU register values of the virtual device or other program calling a service.


Control_Block
include vmm.inc

mov     esi, VM                         ; VM handle

mov     eax, [esi + CB_VM_Status]       ; virtual machine status

mov     eax, [esi + CB_High_Linear]     ; high linear address

mov     eax, [esi + CB_Client_Pointer]  ; points to a Client_Reg_Struc

mov     eax, [esi + CB_VMID]            ; virtual machine ID

The control block for a virtual machine contains information and status for the virtual machine. Virtual devices can use the following symbols to access useful fields in the control block:

Offset	Description

CB_VM_Status	Specifies the status for the virtual machine. It can be a combination of the following values:

Value	Meaning

VMStat_Exclusive	Virtual machine is in exclusive mode.

VMStat_Background	Virtual machine runs in the background.

VMStat_Creating	Virtual machine is being created.

VMStat_Suspended	Virtual machine is not scheduled.

VMStat_Not_Executeable	Virtual machine is partially destroyed.

VMStat_PM_Exec	Virtual machine execution currently in a protected-mode application.

VMStat_PM_App	Virtual machine contains a protected-mode application.

VMStat_PM_Use32	Virtual machine contains a 32-bit protected-mode application.

VMStat_VxD_Exec	Virtual machine has received a call from a virtual device.

VMStat_High_Pri_Back	Virtual machine has high priority background execution.

VMStat_Blocked	Virtual machine is blocked on a semaphore.

VMStat_Awakening	Virtual machine is waking up after being blocked on a semaphore.

VMStat_PageableV86	Virtual machine has pageable V86 memory (protected-mode application). The default behavior for one or more pages in V86 memory has been modified and the _GetV86PageableArray service returns at least one nonzero bit in the array.

VMStat_V86IntsLocked	Virtual machine locks any V86 memory that is not pageable. Locking regardless of the pager type has been enabled for the virtual machine.

VMStat_TS_Sched	Virtual machine is scheduled by the time slicer.

VMStat_Idle	Virtual machine has released its time slice.

VMStat_Closing	Virtual machine has received a Close_VM message.

CB_High_Linear	Specifies the liner address in the VMM linear address space of the virtual machine memory. Virtual devices can add a V86 linear address to this value calculate the location of a virtual machine memory in the VMM address space.

CB_Client_Pointer	Specifies the address of a Client_Reg_Struc structure containing the register values for the virtual machine.

CB_VMID	Specifies the virtual machine identifier.

See Also

Close_VM, Client_Reg_Struc


DemandInfoStruc
include vmm.inc

DemandInfoStruc struc

  DILin_Total_Count  dd  ?   ; size of linear address space in pages

  DIPhys_Count       dd  ?   ; count of phys pages

  DIFree_Count       dd  ?   ; count of free phys pages

  DIUnlock_Count     dd  ?   ; count of unlocked Phys Pages

  DILinear_Base_Addr dd  ?   ; case of pageable address space

  DILin_Total_Free   dd  ?   ; total free linear pages

  DIReserved         dd  10 DUP(?)  ; reserved

DemandInfoStruc ends

The DemandInfoStruc structure contains information about pages that are subject to demand paging.

Member	Description

DILin_Total_Count	Specifies the total number of pages subject to demand paging.

DIPhys_Count	Specifies the total number of physical pages managed by the memory manager.

DIFree_Count	Specifies the number of pages currently in the free pool.

DIUnlock_Count	Specifies the number of pages that are currently unlocked. Free pages are always unlocked.

DILinear_Base_Addr	Specifies the linear address of the first page subject to demand paging. If DILinear_Base_Addr is zero, the pages subject to demand paging are not contiguous.

DILin_Total_Free	Specifies the number of the pages that are currently free as well as subject to demand paging. There is no guarantee that these free pages are contiguous.

DIReserved	Specifies a reserved field. Virtual devices must make no assumptions about the content or purpose of this field.

See Also

_GetDemandPageInfo


Exception_Handler_Struc
include vmm.inc

Exception_Handler_Struc STRUC

EH_Reserved     dd      ?

EH_Start_EIP    dd      ?

EH_End_EIP      dd      ?

EH_Handler      dd      ?

Exception_Handler_Struc ENDS

The Exception_Handler_Struc structure contains information about a ring-0 exception handler.

Member	Description

EH_Reserved	Reserved; must be zero.

EH_Start_EIP	Specifies the starting address of the exception handler's supported range of addresses.

EH_End_EIP	Specifies the ending address of the exception handler's supported range of addresses.

EH_Handler	Points to the exception handler.

See Also

Install_Exception_Handler


InstDataStruc
include vmm.inc

InstDataStruc struc

  InstLinkF     dd      ?   ; RESERVED SET TO 0

  InstLinkB     dd      ?   ; RESERVED SET TO 0

  InstLinAddr   dd      ?   ; Linear address of start of block

  InstSize      dd      ?   ; Size of block in bytes

  InstType      dd      ?   ; Type of the block

InstDataStruc ends

The InstDataStruc structure contain information about an instance data block.

Member	Description

InstLinkF	Reserved. This field is filled in by the instance data manager and must not be used.

InstLinkB	Reserved. This field is filled in by the instance data manager and must not be used.

InstLinAddr	Specifies the linear address of the start of the block of instance data. Thus the correct value for 40:2F would be 42F.

InstSize	Specifies the size in bytes of the instance data block.

InstType	Specifies the instance data type. It can be one of the following values:

Value	Meaning

INDOS_Field	Reserved for special types of MS-DOS internal data which only need to be switched with the virtual machine if the virtual machine is currently INDOS.

ALWAYS_Field	Indicates that the field must always be switched when a virtual machine is switched. All instance data specified by devices should be of this type.

See Also

_AddInstanceItem


IPF_Data
include vmm.inc

IPF_Data    struc

    IPF_LinAddr     dd  ?   ; CR2 address of fault

    IPF_MapPageNum  dd  ?   ; Possible converted page number of fault

    IPF_PTEEntry    dd  ?   ; Contents of PTE that faulted

    IPF_FaultingVM  dd  ?   ; May not = current VM (IPF_V86PgH set)

    IPF_Flags       dd  ?   ; Flags

IPF_Data    ends

The IPF_Data structure contains information about the current invalid page fault.

Member	Description

IPF_LinAddr	Specifies the CR2 address of the page fault.

IPF_MapPageNum	Specifies the possible converted page number of the fault.

IPF_PTEEntry	Specifies the contents of the page-table entry that caused the fault.

IPF_FaultingVM	Specifies the handle identifying the virtual machine that caused the fault. This is not necessarily the current virtual machine.

IPF_Flags	Specifies the invalid-page-fault flags. It can be a combination of the following values:

Value	Meaning

IPF_PgDir	Page directory entry not present (not-present page table).

IPF_V86Pg	Unexpected not-present page in V86.

IPF_V86PgH	Unexpected not-present page in V86 at high linear address.

IPF_InvTyp	Page has invalid not-present type.

IPF_PgErr	Pageswap device could not page for some reason.

IPF_ReFlt	Re-entrant page fault.

IPF_VMM	Page fault caused by a virtual device.

IPF_PM	Page fault caused by virtual machine running in protected mode.

IPF_V86	Page fault caused by virtual machine running in V86 mode.

Comments

Invalid page faults occur in a virtual machine other than the current virtual machine if the high linear address of the virtual machine is accessed. In this case, the IPF_FaultingVM field is set to the handle of the virtual machine that owns the high linear address.

See Also

Hook_Invalid_Page_Fault


Time-Slice Scheduler Services

Adjust_Execution_Time	Adjusts time slice amount

Get_Execution_Focus	Returns handle for execution focus

Get_Time_Slice_Granularity	Returns the minimum time-slice

Get_Time_Slice_Info	Returns scheduled virtual machine information

Get_Time_Slice_Priority	Returns priority

Release_Time_Slice	Releases the current time-slice

Set_Execution_Focus	Assigns execution focus to a virtual machine

Set_Time_Slice_Granularity	Sets the minimum time-slice

Set_Time_Slice_Priority	Sets the time-slice priority

Wake_Up_VM	Restores an idle virtual machine


Adjust_Execution_Time
include vmm.inc

mov     eax, Time       ; number of milliseconds to adjust time slice

move    ebx, VM         ; VM handle

VMMcall Adjust_Execution_Time

The Adjust_Execution_Time service adjusts the amount of execution time a virtual machine is granted with each time slice. Virtual devices, such as the virtual COM device, use this service to temporarily boost the priority of a virtual machine, such as when the virtual machine is receiving an unusually high number of interrupts.

Parameter	Description

Time	Specifies a signed integer value representing the number of milliseconds to add or subtract from the current time-slice granularity value.

VM	Specifies a handle identifying the virtual machine to adjust.

Returns

This service has no return value.

Comments

This service has the same effect on all virtual machines regardless of their time-slice priority. If the specified virtual machine is not on the time-slice list, this service returns immediately (does nothing). This service never forces a nonrunnable virtual machine to execute. A virtual machine not already in the background cannot be forced to run in the background by boosting its execution time.

This service can increase or decrease the execution time for a virtual machine. However, decreasing execution time is not recommended because it defeats the purpose of multitasking. Virtual devices should avoid using this service.

Uses

Flags

See Also

Get_Time_Slice_Granularity, Set_Time_Slice_Granularity


Get_Execution_Focus
include vmm.inc

VMMcall Get_Execution_Focus

mov     [Focus], ebx            ; handle of VM with execution focus

The Get_Execution_Focus service returns the handle of the virtual machine currently having the execution focus. This virtual machine is called the foreground virtual machine.

This service has no parameters.

Returns

The EBX register contains the handle of virtual machine that currently has the execution focus.

Uses

EBX, Flags

See Also

Set_Execution_Focus


Get_Time_Slice_Granularity
include vmm.inc

VMMcall Get_Time_Slice_Granularity

mov     [Granularity], eax          ; minimum time-slice in millisecond

The Get_Time_Slice_Granularity service returns the current time-slice granularity. This value specifies the minimum number of milliseconds a virtual machine runs before being rescheduled.

This service has no parameters.

Returns

The EAX register contains the time-slice granularity in milliseconds.

Uses

EAX, Flags

See Also

Get_Time_Slice_Info, Get_Time_Slice_Priority, Set_Time_Slice_Granularity


Get_Time_Slice_Info
include vmm.inc

VMMcall Get_Time_Slice_Info

mov     [Scheduled], eax    ; number of virtual machines scheduled

mov     [Current], ebx      ; handle of currently scheduled virtual machine

mov     [Idle], ecx         ; number of idle virtual machines

The Get_Time_Slice_Info service returns information about the number of virtual machines currently scheduled by the time-slicer, and the number of virtual machines that are idle.

This is an asynchronous service.

This service has no parameters.

Returns

The EAX, EBX and ECX registers contain the following information:

Register	Description

EAX	Contains the number of virtual machines scheduled.

EBX	Contains the handle of the currently scheduled virtual machine.

ECX	Contains the number of scheduled virtual machines that are currently idle.

Uses

EAX, EBX, ECX, Flags

See Also

Get_Time_Slice_Granularity, Get_Time_Slice_Priority


Get_Time_Slice_Priority
include vmm.inc

mov     ebx, VM             ; VM handle

VMMcall Get_Time_Slice_Priority

mov     [Flags], eax        ; flags from CB_VM_Status

mov     [Foreground], ecx   ; foreground time-slice priority

mov     [Background], edx   ; background time-slice priority

mov     [CPUTime], esi      ; percentage of total CPU time used

The Get_Time_Slice_Priority service returns the time-slice execution flags, the foreground and background priorities, and the percent of CPU usage for a specified virtual machine.

Parameter	Description

VM	Specifies a handle identifying the virtual machine for which to retrieve information.

Returns

The EAX, ECX, EDX, and ESI registers contain the following information:

Register	Description

EAX	Specifies status flags from the CB_VM_Status field in the virtual machine's control block. It can be one of the following values:

Value	Meaning

VMStat_Exclusive	Exclusive execution.

VMStat_Background	Background execution.

VMStat_High_Pri_Back	High-priority background execution.

ECX	Specifies the foreground time-slice priority. The high word is always 0.

EDX	Specifies the background time-slice priority. The high word is always 0.

ESI	Specifies the percentage of total CPU time used by the virtual machine.

Comments

The percentage of CPU time indicates the maximum amount of time the virtual machine can run. If the virtual machine releases its time slice, this actual amount of CPU time will be lower because the system grants the released time to other virtual machines.

Uses

EAX, ECX, EDX, ESI, Flags

See Also

Get_Time_Slice_Granularity, Get_Time_Slice_Info


Release_Time_Slice
include vmm.inc

VMMcall Release_Time_Slice

The Release_Time_Slice service discards any remaining time in the current time slice and immediately starts a new time slice for the next virtual machine in the time-slice queue.

This service effectively suspends the current virtual machine. The virtual machine remains suspended until another virtual machine or a hardware interrupt calls the Wake_Up_VM service for this virtual machine.

This service has no parameters.

Returns

This service has no return value.

Comments

This service returns immediately (does nothing) if the current virtual machine is the only one in the time-slice queue.

Virtual devices should use this service whenever the virtual machine is idle. If the current virtual machine is a background virtual machine, this service releases the time slice and decreases the execution time by -500 milliseconds. If the current virtual machine has the execution focus or is a high-priority background virtual machine, this service releases the time slice but does not adjust the execution time.

Uses

Flags

See Also

Adjust_Execution_Time, Get_Execution_Focus, Wake_Up_VM


Set_Execution_Focus
include vmm.inc

mov     ebx, VM             ; VM handle

VMMcall Set_Execution_Focus

jc      focus_not_set       ; carry set if the focus cannot be set

The Set_Execution_Focus service assigns the execution focus to the specified virtual machine.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to receive the execution focus.

Returns

The carry flag is clear if the execution focus was set to the specified virtual machine. Otherwise, the carry flag is set.

Comments

When a virtual machine has the execution focus, it executes using its foreground priority. If the specified virtual machine has exclusive execution priority, it is the only virtual machine to receive time slices. If the specified virtual machine does not have exclusive execution priority, the system schedules background virtual machines as well.

When a virtual machine receives the execution focus, the system suspends all other virtual machines except the system virtual machine and background virtual machines.

Only the system virtual machine can assign the execution focus to other virtual machines; a nonsystem virtual machine can only assign the execution focus to itself.

Uses

Flags

See Also

Get_Execution_Focus, Set_Time_Slice_Granularity, Set_Time_Slice_Priority


Set_Time_Slice_Granularity
include vmm.inc

mov     eax, Time               ; minimum time-slice in milliseconds

VMMcall Set_Time_Slice_Granularity

The Set_Time_Slice_Granularity service sets the minimum time-slice granularity. This value specifies the minimum number of milliseconds a virtual machine runs before being rescheduled.

Parameter	Description

Time	Specifies the minimum time-slice granularity in milliseconds.

Returns

This service has no return value.

Comments

Small time-slice granularity values make multitasking appear smoother, but require high numbers of task switches and increase execution overhead. Large values allow more time for the virtual machines to execute but may make execution look intermittent to the user.

Uses

Flags

See Also

Get_Time_Slice_Granularity, Set_Time_Slice_Priority


Set_Time_Slice_Priority
include vmm.inc

mov     eax, Flags          ; status flags

mov     ebx, VM             ; VM handle

mov     ecx, Foreground     ; foreground priority

mov     edx, Background     ; background priority

VMMcall Set_Time_Slice_Priority

The Set_Time_Slice_Priority service sets the time-slice execution flags and the foreground and background priorities for a specified virtual machine.

Parameter	Description

Flags	Specifies status flags for the CB_VM_Status field in the virtual machine's control block. It can be one of the following values:

Value	Meaning

VMStat_Exclusive	Exclusive execution.

VMStat_Background	Background execution.

VMStat_High_Pri_Back	High-priority background execution.

VM	Specifies a handle identifying the virtual machine to change.

Foreground	Specifies the foreground time-slice priority. The high word must be 0.

Background	Specifies the background time-slice priority. The high word must be 0.

Returns

The carry flag is clear if the service successfully sets the time-slice priority. Otherwise, the carry flag is set.

Comments

To change the time-slice priority, a virtual should retrieve the current time-slice priority using the Get_Time_Slice_Priority service, modify the returned values, and use the modified values as input parameters to this service.

Example

The following example assigns a virtual machine to the background:

mov     ebx, [VM]

VMMcall Get_Time_Slice_Priority

or      eax, VMStat_Background

VMMcall Set_Time_Slice_Priority

Uses

Flags

See Also

Get_Time_Slice_Priority, Set_Time_Slice_Granularity


Wake_Up_VM
include vmm.inc

mov     ebx, VM         ; VM handle

VMMcall Wake_Up_VM

The Wake_Up_VM service restores an idle virtual machine, allowing the system to schedule the virtual machine for subsequent time slices. A virtual machine is idle if it has called the Release_Time_Slice service or has set the VMStat_Idle flag in the CB_VM_Status field of its control block.

Parameter	Description

VM	Specifies a handle identifying the virtual machine to restore.

Returns

This service has no return value.

Comments

If the specified virtual machine is not idle, this service returns immediately (does nothing).

Uses

Flags

See Also

Release_Time_Slice


Timing Services

Cancel_Time_Out	Cancels a time-out

Get_Last_Updated_System_Time	Returns system time in milliseconds

Get_Last_Updated_VM_Exec_Time	Returns execution time for virtual machine

Get_System_Time	Returns system time in milliseconds

Get_VM_Exec_Time	Returns execution time for virtual machine

Set_Global_Time_Out	Sets a global time-out

Set_VM_Time_Out	Sets a time-out for a virtual machine

Update_System_Clock	Updates the system clock


Cancel_Time_Out
include vmm.inc

mov     esi, TimeOut     ; time-out handle

VMMcall Cancel_Time_Out

The Cancel_Time_Out service cancels a time-out that was scheduled using the Set_VM_Time_Out or Set_Global_Time_Out service.

Parameter	Description

TimeOut	Specifies a handle identifying the time-out to cancel. If this parameter is zero, the service returns immediately (does nothing).

Returns

This service has no return value.

Comments

This service makes the time-out handle invalid; the virtual device must not attempt to use the handle in subsequent calls to services.

Uses

Flags

See Also

Set_Global_Time_Out, Set_VM_Time_Out


Get_Last_Updated_System_Time
include vmm.inc

VMMcall Get_Last_Updated_System_Time

mov     [SysTime], eax          ; system time in milliseconds

The Get_Last_Updated_System_Time service returns the time in milliseconds since Windows was started. This service is accurate to approximately 50 milliseconds.

This is an asynchronous service.

This service has no parameters.

Returns

The EAX register contains the elapsed time in milliseconds since Windows started.

Comments

This service does not detect rollover of the clock which occurs every 49 1/2 days. If a virtual device is sensitive to rollover, it should schedule a time-out every 30 days

Although the Get_System_Time service is more accurate than this service, Get_System_Time must call the timer device to update the clock so it is slower than Get_Last_Updated_System_Time.

Uses

EAX, Flags

See Also

Get_System_Time


Get_Last_Updated_VM_Exec_Time
include vmm.inc

VMMcall Get_Last_Updated_VM_Exec_Time

mov     [ExecTime], eax     ; time in milliseconds that VM has run

The Get_Last_Updated_VM_Exec_Time service returns the amount of time that the current virtual machine has run. This service is accurate to approximately 50 milliseconds.

This is an asynchronous service.

This service has no parameters.

Returns

The EAX register contains the execution time for the current virtual machine.

Comments

When the system creates a virtual machine, it sets the execution time for the virtual machine to zero. The system increases the execution time only when the virtual machine actually runs. Therefore the execution does not reflect the length of time the virtual machine has existed, but indicates the amount of time the current virtual machine has run.

Uses

EAX, Flags

See Also

Get_VM_Exec_Time


Get_System_Time
include vmm.inc

VMMcall Get_System_Time

mov     [SysTime], eax          ; system time in milliseconds

The Get_System_Time service returns the time in milliseconds since Windows started. This service is accurate to 1 millisecond.

This is an asynchronous service.

This service has no parameters.

Returns

The EAX register contains the elapsed time in milliseconds since Windows started.

Comments

This service does not detect rollover of the clock which occurs every 49 1/2 days. If a virtual device is sensitive to rollover, it should schedule a time-out every 30 days

Although the Get_System_Time service is more accurate than the Get_Last_Updated_System_Time service, Get_System_Time must call the timer device to update the clock so it is slower than Get_Last_Updated_System_Time.

Uses

EAX, Flags

See Also

Get_Last_Updated_System_Time


Get_VM_Exec_Time
include vmm.inc

VMMcall Get_VM_Exec_Time

mov     [ExecTime], eax     ; time in milliseconds that VM has run

The Get_VM_Exec_Time service returns the amount of time that the current virtual machine has run. This service is accurate to 1 millisecond.

This is an asynchronous service.

This service has no parameters.

Returns

The EAX register contains the execution time for the current virtual machine.

Comments

When the system creates a virtual machine, it sets the execution time for the virtual machine to zero. The system increases the execution time only when the virtual machine actually runs. This means the execution time indicates the amount of time the current virtual machine has run, not the length of time since it was created.

Although the Get_VM_Exec_Time service is more accurate than the Get_Last_Updated_VM_Exec_Time service, Get_VM_Exec_Time must call the timer device to update the clock so it is slower than Get_Last_Updated_VM_Exec_Time.

Uses

EAX, Flags

See Also

Get_Last_Updated_VM_Exec_Time


Set_Global_Time_Out
include vmm.inc

mov     eax, Time                       ; number of milliseconds to time-out

mov     edx, OFFSET32 RefData           ; points to reference data

mov     esi, OFFSET32 TimeOutCallback   ; points to callback procedure

VMMcall Set_Global_Time_Out

mov     [TimeOut], esi                  ; time-out handle

The Set_Global_Time_Out service schedules a time-out to occur after the specified number of milliseconds have elapsed.

Parameter	Description

Time	Specifies the number of milliseconds to wait until calling the time-out callback procedure.

RefData	Points to reference data to be passed to the callback procedure.

TimeOutCallback	Points to the callback procedure. See the Comments section for more information about the procedure.

Returns

The ESI register contains the handle of the time-out if the service is successful. Otherwise, the ESI is zero indicating that the time-out is not scheduled.

Comments

The system calls the time-out callback procedure when the specified number of milliseconds elapse. The system calls the procedure as follows:

mov     ebx, VM                 ; current VM handle

mov     ecx, Extra              ; number of milliseconds since time-out

mov     edx, OFFSET32 RefData   ; points to reference data

mov     ebp, OFFSET32 crs       ; points to Client_Reg_Struc

call    [TimeOutCallback]

The VM parameter is a handle specifying the current virtual machine. The RefData parameter points to the reference data for the callback procedure, and the crs parameter points to a Client_Reg_Struc structure that contains the register values for the current virtual machine.

The Extra parameter specifies the number of milliseconds that have elapsed since the actual time-out occurred. Time-outs are often delayed by 10 milliseconds or more because the normal system timer runs at 20 milliseconds or slower.

If a virtual device needs more accurate time-outs, it must increase the timer interrupt frequency using virtual timer device (VTD) services.

Uses

ESI, Flags

See Also

Set_VM_Time_Out


Set_VM_Time_Out
include vmm.inc

mov     eax, Time                       ; number of milliseconds to time-out

mov     ebx, VM                         ; VM handle

mov     edx, OFFSET32 RefData           ; points to reference data

mov     esi, OFFSET32 TimeOutCallback   ; points to callback procedure

VMMcall Set_VM_Time_Out

mov     [TimeOut], esi                  ; time-out handle

The Set_VM_Time_Out service schedules a time-out that occurs after the specified virtual machine has run for the specified length of time. The system calls the time-out callback procedure only after the virtual machine has run for Time milliseconds. Time that elapses while other virtual machines run is not counted.

Parameter	Description

Time	Specifies the number of milliseconds to wait until calling the time-out callback procedure.

VM	Specifies a handle identifying the virtual machine.

RefData	Points to reference data to be passed to the callback procedure.

TimeOutCallback	Points to the callback procedure. See the Comments section for more information about the procedure.

Returns

The ESI register contains the handle of the time-out if the service is successful. Otherwise, the ESI is zero indicating that the time-out is not scheduled.

Comments

The system calls the time-out callback procedure when the virtual machine runs for the specified number of milliseconds. The system calls the procedure as follows:

mov     ebx, VM                 ; current VM handle

mov     ecx, Extra              ; number of milliseconds since time-out

mov     edx, OFFSET32 RefData   ; points to reference data

mov     ebp, OFFSET32 crs       ; points to Client_Reg_Struc

call    [TimeOutCallback]

The VM parameter is a handle specifying the virtual machine for which the time-out was scheduled. The RefData parameter points to the reference data for the callback procedure, and the crs parameter points to a Client_Reg_Struc structure that contains the register values for the virtual machine.

The Extra parameter specifies the number of milliseconds that have elapsed since the actual time-out occurred. Time-outs are often delayed by 10 milliseconds or more because the normal system timer runs at 20 milliseconds or slower.

If a virtual device needs more accurate time-outs, it must increase the timer interrupt frequency using virtual timer device (VTD) services.

Uses

ESI, Flags

See Also

Set_Global_Time_Out


Update_System_Clock
include vmm.inc

mov     ecx, Time           ; elapsed time in milliseconds

VMMcall Update_System_Clock

The Update_System_Clock service updates the current system time and the current virtual machine's execution time.

This service is reserved for exclusive use by the virtual timer device. If other virtual devices call this service, the VMM timing services will behave incorrectly.

Parameter	Description

Time	Specifies the number of milliseconds that have elapsed since the last call to this service. The service adds this amount to the system time maintained by the VMM.

Returns

This service has no return value.

Comments

The virtual timer device must disabled interrupts before calling this service.

Uses

Flags


Interrupts and Callback Services

Build_Int_Stack_Frame	Builds a stack frame for an interrupt

Call_When_VM_Ints_Enabled	Installs an interrupts-enabled callback

Disable_VM_Ints	Disables interrupts for the virtual machine

Enable_VM_Ints	Enables interrupts for the virtual machine

Get_PM_Int_Type	Returns the type of interrupt vector

Get_PM_Int_Vector	Returns a protected-mode interrupt address

Get_V86_Int_Vector	Returns an real-mode interrupt address

Hook_V86_Int_Chain	Installs a hook procedure for a V86 interrupt

Set_PM_Int_Type	Sets the protected-mode interrupt type

Set_PM_Int_Vector	Sets a protected-mode interrupt vector

Set_V86_Int_Vector	Sets a real-mode interrupt vector

Simulate_Far_Call	Simulates a far call

Simulate_Far_Jmp	Simulates a jump

Simulate_Far_Ret	Simulates a far return

Simulate_Far_Ret_N	Simulates a far return with parameters

Simulate_Int	Simulates an interrupt

Simulate_Iret	Simulates a return from an interrupt

Simulate_Pop	Simulates a pop instruction

Simulate_Push	Simulates a push instruction


Build_Int_Stack_Frame
include vmm.inc

mov     cx, Segment        ; code segment of routine to call

mov     edx, Offset        ; offset of routine to call

VMMcall Build_Int_Stack_Frame

The Build_Int_Stack_Frame service prepares the current virtual machine to execute an interrupt routine. This service saves the current Client_CS, Client_IP, and Client_Flags registers on the virtual machine's stack and sets the Client_CS and Client_IP registers to the address of the interrupt routine specified by the Segment and Offset parameters. When execution resumes in the virtual machine (such as when the Resume_Exec service is called), the virtual machine executes the interrupt routine. The interrupt routine continues to run until it executes an iret instruction.

Parameter	Description

Segment	Specifies the segment address or segment selector for the code segment containing the interrupt routine.

Offset	Specifies the offset of interrupt routine. If the specified code segment is a 16-bit segment, the high word of this parameter must be 0.

Returns

This service has no return value.

Example

The following example executes the interrupt routine in the code segment specified by My_Segment at the offset My_Offset:

VMMcall Begin_Nest_Exec

mov     cx, [My_Segment]

mov     edx, [My_Offset]

VMMcall Build_Int_Stack_Frame

VMMcall Resume_Exec

VMMcall End_Nest_Exec

Uses

Client_CS, Client_EIP, Client_ESP, Client_Flags, Flags

See Also

Simulate_Far_Call


Call_When_VM_Ints_Enabled
include vmm.inc

mov     edx, OFFSET32 RefData   ; points to reference data

mov     esi, OFFSET32 Callback  ; points to callback procedure

VMMcall Call_When_VM_Ints_Enabled

The Call_When_VM_Ints_Enabled service installs a callback procedure that the system calls whenever the virtual machine enables interrupts. This service calls the callback procedure immediately if interrupts are already enabled. Virtual devices use this service to receive notification when the virtual machines enables interrupts.

Parameter	Description

RefData	Points to reference data to be passed to the callback procedure.

Callback	Points to the callback procedure. See the Comments section for more information about the procedure.

Returns

This service has no return value.

Comments

It is usually more convenient to use the Call_Priority_VM_Event service instead of calling this service directly. However, this service is faster.

The system calls the callback procedure as follows:

mov     ebx, VM                  ; current VM handle

mov     edx, OFFSET32 RefData    ; points to reference data

mov     ebp, OFFSET32 crs        ; points to a Client_Reg_Struc

call    [Callback]

The VM parameter is a handle identifying the current virtual machine, RefData points to the reference data specified when the callback procedure was installed, and crs points to a Client_Reg_Struc structure containing the register values for the virtual machine.

The callback procedure may use EAX, EBX, ECX, EDX, ESI, EDI, and Flags.

Uses

Client_Flags, Flags

See Also

Call_When_Idle, Call_When_Not_Critical, Call_When_Task_Switched


Disable_VM_Ints
include vmm.inc

VMMcall Disable_VM_Ints

The Disable_VM_Ints service disables interrupts during virtual machine execution for the current virtual machine. This has the same effect as the virtual machine executing a cli instruction.

This service has no parameters.

Returns

This service has no return value.

Uses

Flags

See Also

Enable_VM_Ints


Enable_VM_Ints
include vmm.inc

VMMcall Enable_VM_Ints

The Enable_VM_Ints service enables interrupts during virtual machine execution for the current virtual machine. This has the same effect as the virtual machine executing an sti instruction.

This service has no parameters.

Returns

This service has no return value.

Comments

Virtual devices use this service to permit callback procedures installed by the Call_When_Ints_Enabled or Call_Priority_VM_Event service to be called. The system does not call these callback procedures immediately. Instead it waits until the next event occurs. This means the virtual machine's state does not change while this service executes.

Uses

Flags

See Also

Call_Priority_VM_Event, Call_When_VM_Ints_Enabled, Disable_VM_Ints


Get_PM_Int_Type
include vmm.inc

mov     eax, Interrupt      ; number of interrupt to check

VMMcall Get_PM_Int_Type

mov     [Type], edx         ; 0 if trap gate, otherwise interrupt gate

The Get_PM_Int_Type service determines whether a protected-mode interrupt vector is an interrupt gate or trap gate type interrupt.

Parameter	Description

Interrupt	Specifies the number of the interrupt to check.

Returns

The EDX register contains zero if the specified interrupt corresponds to a trap gate. The EDX register contains a nonzero value if the interrupt corresponds to an interrupt gate.

Comments

An interrupt through an interrupt gate automatically clears the interrupt flag bit to disable interrupts. Interrupts through a trap gate do not modify the interrupt bit. All protected-mode interrupts default to the trap gate type, but virtual devices such as the virtual PIC device, may change some trap gates to interrupt gates so that hardware interrupts disable interrupts. The virtual PIC device leaves software interrupts, such as Interrupt 21h, unchanged. This avoids an unnecessary ring transition by eliminating the need for the software interrupt handlers to execute an sti instruction.

Uses

EDX, Flags

See Also

Get_PM_Int_Vector, Set_PM_Int_Type


Get_PM_Int_Vector
include vmm.inc

mov     eax, Interrupt      ; number of interrupt to check

VMMcall Get_PM_Int_Vector

mov     [Segment], cx       ; segment selector for interrupt routine

mov     [Offset], edx       ; offset to interrupt routine

The Get_PM_Int_Vector service returns the address of the interrupt routine for the specified protected-mode interrupt in the current virtual machine.

Parameter	Description

Interrupt	Specifies the number of the interrupt to check.

Returns

The CX register contains the segment selector of the interrupt routine, and the EDX register contains the offset of the interrupt routine. If the code segment is a 16-bit segment, the high word of the EDX register is zero.

The zero flag is set if the interrupt address points to the default interrupt handler; the flag is clear if a virtual device has hooked the interrupt.

Comments

The system maintains a protected-mode interrupt vector table for each virtual machine. By default, each table entry points to a protected-mode breakpoint procedure that reflects the interrupt to V86 mode.

Uses

ECX, EDX, Flags

See Also

Get_PM_Int_Type, Set_PM_Int_Vector


Get_V86_Int_Vector
include vmm.inc

mov     eax, Interrupt      ; number of interrupt to check

VMMcall Get_V86_Int_Vector

mov     [Segment], cx       ; segment address for interrupt routine

mov     [Offset], edx       ; offset to interrupt routine

The Get_V86_Int_Vector service returns the address of the interrupt routine for the specified real-mode interrupt in the current virtual machine.

Parameter	Description

Interrupt	Specifies the number of the interrupt to check.

Returns

The CX register contains the segment address of the interrupt routine and the EDX register contains the offset of the interrupt routine (the high word is always zero).

Uses

ECX, EDX, Flags

See Also

Get_PM_Int_Vector, Set_V86_Int_Vector


Hook_V86_Int_Chain
include vmm.inc

mov     eax, Interrupt          ; number of interrupt to hook

mov     esi, OFFSET32 HookProc  ; points to hook procedure

VMMcall Hook_V86_Int_Chain

jc      not_installed       ; carry set if procedure not installed

The Hook_V86_Int_Chain service installs a hook procedure that the system calls whenever the specified interrupt occurs. Virtual devices use this service to monitor software interrupts and simulated hardware interrupts in V86 mode.

This service is only available during initialization.

Parameter	Description

Interrupt	Specifies the number of the interrupt for which to install the hook procedure.

HookProc	Points to the hook procedure. See the Comments section for more information about this procedure.

Returns

The carry flag is clear if the hook procedure is installed. The carry flag is set to indicate an error such as an invalid interrupt number.

Comments

The system calls the hook procedure whenever the corresponding interrupt occurs, a virtual device calls the Simulate_Int service, or the system simulates a hardware interrupt. This means a hook procedure must make no assumptions about the origin of the interrupt.

The system calls the procedure as follows:

mov     eax, Interrupt      ; number of interrupt hooked

mov     ebx, VM             ; current VM handle

mov     ebp, OFFSET32 crs   ; points to a Client_Reg_Struc

call    [HookProc]

jc      pass_to_next        ; carry set if interrupt not serviced

The Interrupt parameter is the number of the current interrupt, VM is a handle identifying the current virtual machine, and crs points to a Client_Reg_Struc structure containing the register values of the current virtual machine. If the hook procedure services the interrupt, it must clear the carry flag to prevent the system from passing the interrupt to the next hook procedure.

Any number of virtual devices can install a hook procedure for a given interrupt. The system always calls the last hook procedure first. A hook procedure either services the interrupt or directs the system to pass the interrupt to the next hook procedure. If no hook procedure services the interrupt, the system reflects the interrupt to the virtual machine.

This service is recommended instead of hooking the V86 interrupt vector directly.

Uses

Flags

See Also

Set_V86_Int_Vector, Simulate_Int


Set_PM_Int_Type
include vmm.inc

mov     eax, Interrupt      ; interrupt number

mov     edx, Type           ; zero for trap gate, nonzero for interrupt gate

VMMcall Set_PM_Int_Type

The Set_PM_Int_Type service sets the gate type for a protected-mode interrupt vector.

Parameter	Description

Interrupt	Specifies the number of the interrupt to set.

Type	Specifies the type of gate to set. If this parameter is zero, the service sets a trap gate; if nonzero, it sets an interrupt gate.

Returns

This service has no return value.

Comments

An interrupt through an interrupt gate automatically clears the interrupt flag bit to disable interrupts. Interrupts through trap gate do not modify the interrupt bit. All protected-mode interrupts default to the trap gate type, but virtual devices such as the virtual PIC device, may change some trap gates to interrupt gates so that hardware interrupts disable interrupts. The virtual PIC device leaves software interrupts, such as Interrupt 21h, unchanged. This avoids an unnecessary ring transition by eliminating the need for the software interrupt handlers to execute an sti instruction.

Uses

Flags

See Also

Get_PM_Int_Type, Set_PM_Int_Vector


Set_PM_Int_Vector
include vmm.inc

mov     eax, Interrupt       ; interrupt number

mov     cx, Segment          ; segment selector for interrupt routine

mov     edx, Offset          ; offset to interrupt routine

VMMcall Set_PM_Int_Vector

The Set_PM_Int_Vector service sets the specified protected-mode interrupt vector to the address of the given interrupt routine.

Parameter	Description

Interrupt	Specifies the number of the interrupt to set.

Segment	Specifies the selector of the code segment containing the interrupt routine.

Offset	Specifies the offset to the interrupt routine. If the code segment containing the routine is a 16-bit segment, the high word of this parameter must be zero.

Returns

This service has no return value.

Comments

If the Set_PM_Int_Vector service is called before the Sys_VM_Init control call, the installed interrupt routine becomes part of the default interrupt vector table for every virtual machine. Otherwise, this service affects the interrupt vector table for the current virtual machine only. By default, each table entry points to a protected-mode breakpoint procedure that reflects the interrupt to V86 mode.

Uses

Flags

See Also

Get_PM_Int_Vector, Set_PM_Int_Type, Set_V86_Int_Vector


Set_V86_Int_Vector
include vmm.inc

mov     eax, Interrupt       ; interrupt number

mov     cx, Segment          ; segment address for interrupt routine

mov     edx, Offset          ; offset to interrupt routine

VMMcall Set_V86_Int_Vector

The Set_V86_Int_Vector service sets the specified real-mode interrupt vector to the address of the given interrupt routine.

Parameter	Description

Interrupt	Specifies the number of the interrupt to set.

Segment	Specifies the address of the code segment containing the interrupt routine.

Offset	Specifies the offset to the interrupt routine. The high word must be zero.

Returns

This service has no return value.

Comments

If the Set_V86_Int_Vector service is called before the Sys_VM_Init message, the installed interrupt routine becomes part of the default interrupt vector table for every virtual machine. Otherwise, this service affects the interrupt vector table for the current virtual machine only.

Uses

Flags

See Also

Get_V86_Int_Vector, Set_PM_Int_Vector


Simulate_Far_Call
include vmm.inc

mov     cx, Segment       ; segment containing procedure to call

mov     edx, Offset       ; offset of procedure to call

VMMcall Simulate_Far_Call

The Simulate_Far_Call service simulates a far call to a procedure in the the current virtual machine. This service sets the Client_CS and Client_IP registers to the specified procedure address after saving the original Client_CS and Client_IP registers on the stack of the current virtual machine. When the virtual machine resumes execution (such as when the Resume_Exec service is called), the system executes the specified procedure and returns only when the procedure executes a far ret instruction.

Parameter	Description

Segment	Specifies the segment selector or address of the code segment containing the procedure to call.

Offset	Specifies the offset, relative to the beginning of the given segment, to the procedure to call. If the code segment is a 16-bit segment, the high word must be zero.

Returns

This service has no return value.

Uses

Client_CS, Client_EIP, Client_SP, Flags

See Also

Build_Int_Stack_Frame, Simulate_Far_Jmp


Simulate_Far_Jmp
include vmm.inc

mov     cx, Segment       ; segment containing procedure to jump to

mov     edx, Offset       ; offset to procedure to jump to

VMMcall Simulate_Far_Jmp

The Simulate_Far_Jmp service simulates a far jump to a procedure in the current virtual machine. This service sets the Client_CS and Client_IP registers to the specified address. When the virtual machine resumes execution (such as when the Resume_Exec service is called), the system executes the specified procedure.

Parameter	Description

Segment	Specifies the segment selector or address of the code segment containing the procedure to jump to.

Offset	Specifies the offset, relative to the beginning of the given segment, to the procedure to jump to. If the code segment is a 16-bit segment, the high word must be zero.

Returns

This service has no return value.

Uses

Client_CS, Client_EIP, Flags

See Also

Simulate_Far_Call


Simulate_Far_Ret
include vmm.inc

VMMcall Simulate_Far_Ret

The Simulate_Far_Ret service simulates a far return in the current virtual machine. This service pops the top two words (or double-words) from the stack of the current virtual machine and copies these values to the Client_CS and Client_EIP or Client_IP registers.

This service has no parameters.

Returns

This service has no return value.

Comments

This services pops two word values from the stack if the segment containing the address is a 16-bit segment. Otherwise, this service pops two double-word values.

Uses

Flags

See Also

Simulate_Far_Call, Simulate_Far_Ret_N


Simulate_Far_Ret_N
include vmm.inc

mov     eax, Bytes          ; number of bytes to pop from stack

VMMcall Simulate_Far_Ret_N

The Simulate_Far_Ret_N service simulates a far return in the current virtual machine. This service pops the top two words (or double words) from the stack of the current virtual machine, and places the values in the Client_CS and Client_EIP or Client_IP registers. It then subtracts the Bytes parameter from the Client_ESP or Client_ESP register, effectively popping any pushed parameters from the stack.

Parameter	Description

Bytes	Specifies the number of bytes to pop from the stack.

Returns

This service has no return value.

Uses

Client_CS, Client_EIP, Client_ESP, Flags

See Also

Simulate_Far_Call, Simulate_Far_Ret


Simulate_Int
include vmm.inc

mov     eax, Interrupt      ; interrupt number

VMMcall Simulate_Int

The Simulate_Int service simulates an interrupt in the current virtual machine. The service first calls any hook procedures set by the Hook_V86_Int_Chain service. If no hook procedure services the interrupt, this service pushes the Client_Flags, Client_CS, and Client_IP registers on the stack of the current virtual machine. When the virtual machine resumes execution (such as when an Resume_Exec service is called), the system carries out the simulated interrupt and executes the corresponding V86 mode interrupt routine.

The virtual PIC device uses this service to simulate hardware interrupts. Other virtual devices use the Exec_Int service to simulate interrupts.

Parameter	Description

Interrupt	Specifies the number of the interrupt to simulate.

Returns

This service has no return value.

Comments

If the virtual machine is currently in V86 mode, this service simulates a V86 interrupt. Otherwise, the service simulates a protected-mode interrupt. Simulating an interrupt in a virtual machine running a protected-mode application can have undesirable effects if the corresponding interrupt attempts to reflect the interrupt to V86 mode.

Virtual devices that need immediate execution of an interrupt should use the Exec_Int service in a nested execution block.

Uses

Client_CS, Client_EIP, Client_Flags, Flags

See Also

Exec_Int


Simulate_Iret
include vmm.inc

VMMcall Simulate_Iret

The Simulate_Iret service simulates a return from an interrupt. This service pops the top three word or double-word values from the stack of the current virtual machine, and places the values in the Client_Flags, Client_CS, and Client_EIP or Client_IP registers.

This service has no parameters.

Returns

This service has no return value.

Comments

This service pops three word values from the stack if the segment corresponding to the return address is a 16-bit segment. Otherwise, the service pops three double-word values.

Uses

Client_CS, Client_EIP, Client_ESP, Client_Flags, Flags

See Also

Simulate_Int


Simulate_Pop
include vmm.inc

VMMcall Simulate_Pop

mov     [Value], eax        ; value popped from stack

The Simulate_Pop service returns the word or double-word value at the top of the stack of the current virtual machine, and adds two or four to the Client_ESP register.

This service has no parameters.

Returns

The EAX register contains the value popped from virtual machine stack. The high word is zero if in V86 mode or the virtual machine is running a 16-bit program.

Uses

EAX, Client_ESP, Flags

See Also

Simulate_Push


Simulate_Push
include vmm.inc

mov     eax, Value          ; value to push

VMMcall Simulate_Push

The Simulate_Push service pushes a word or double-word value on the stack of the current virtual machine and subtracts two or four from the Client_ESP register.

Parameter	Description

Value	Specifies the value to push on the stack. In V86 mode or when the virtual machine is running a 16-bit program, only the low word is pushed.

Returns

This service has no return value.

Uses

Client_ESP, Flags

See Also

Simulate_Pop


Block Device Services

BlockDev_Command_Complete	Completes a command

BlockDev_Find_Int13_Drive	Returns block device descriptor

BlockDev_Get_Device_List	Returns block device descriptor list

BlockDev_Get_Version	Returns block device version

BlockDev_Register_Device	Registers a block device

BlockDev_Send_Command	Sends a command to a block device

BlockDev_Synchronous_Command	Sends synchronous commands

BlockDev_API_Hw_Detect_Start	Signals start of hardware detection

BlockDev_API_Hw_Detect_End	Signals end of hardware detection

BlockDev_API_Int13_Chain_Check	Signal that block device is about to load

BlockDev_Command_Block	Block device command information

BlockDev_Device_Descriptor	Information about a block device


BlockDev_Command_Complete
include blockdev.inc

mov     edi, OFFSET32 bdd   ; points to a BlockDev_Device_Descriptor

mov     esi, OFFSET32 bcb   ; points to BlockDev_Command_Block

VXDcall BlockDev_Command_Complete

The BlockDev_Command_Complete service calls the callback procedure specified in the BlockDev_Device_Descriptor structure. After the callback procedure returns, BlockDev_Command_Complete sends the pending command (if any) to the block device's command procedure. The service sends pending commands only if the BDF_Serial_Cmd flag is set in the BDD_Flags field in the device's BlockDev_Device_Descriptor structure.

A block device driver should call this service whenever it completes a command.

Parameter	Description

bdd	Points to BlockDev_Device_Descriptor structure containing information about the block device.

bcb	Points to a BlockDev_Command_Block structure containing information about the command just completed.

Returns

This service has no return value.

Comments

The callback procedure preserves all registers and BlockDev_Command_Complete preserves the ESI and EDI registers.

This service enables interrupts.

Uses

EAX, EBX, EDX returned from client, Flags

See Also

BlockDev_Command_Block, BlockDev_Device_Descriptor


BlockDev_Find_Int13_Drive
include blockdev.inc

mov     al, DriveNum            ; Interrupt 13h drive number

VXDcall BlockDev_Find_Int13_Drive

jc      Error                   ; error if carry set

mov     dword ptr [bdd], edi    ; points to BlockDev_Device_Descriptor

The BlockDev_Find_Int13_Drive service returns a pointer to the BlockDev_Device_Descriptor structure for a specified Interrupt 13h drive.

This service is available during initialization only.

Parameter	Description

DriveNum	Specifies an Interrupt 13h drive number.

Returns

If the carry flag is clear, the EDI register contains the address of the BlockDev_Device_Descriptor structure for the specified drive. Otherwise, the carry flag is set to indicate an error.

Comments

The service sets the carry flag if the specified Interrupt 13h block device driver is not installed.

Uses

EDI, Flags

See Also

BlockDev_Device_Descriptor


BlockDev_Get_Device_List
include blockdev.inc

VXDcall BlockDev_Get_Device_List

mov     dword ptr [bdd], edi    ; points to first BlockDev_Device_Descriptor

The BlockDev_Get_Device_List service returns a pointer to the first BlockDev_Device_Descriptor structure in the list of such structures maintained by the virtual device.

This service has no entry parameters.

Returns

The EDI register points to the first BlockDev_Device_Descriptor structure in the block device list. The register is 0 if no list exists.

Comments

Other virtual devices typically call this service to retrieve the information they need to send commands to the block device. The other virtual devices send commands to the block device using the BlockDev_Send_Command service.

Uses

ECX

See Also

BlockDev_Send_Command, BlockDev_Device_Descriptor


BlockDev_Get_Version
include blockdev.inc

VXDcall BlockDev_Get_Version

mov     dword ptr [version], eax    ; block device version number

mov     dword ptr [flags], ecx      ; block device flags

The BlockDev_Get_Version service returns the version number and flags for the virtual block device.

Parameter	Description

This service has no entry parameters.

Returns

The service returns values in the following registers:

Register	Value

EAX	Specifies the version number for the virtual block device.

ECX	Specifies the flags for the virtual block device. Bit 0 must be set to 0 for compatibility with Windows 3.0. All other bits currently reserved and must be 0.

Uses

EAX, ECX


BlockDev_Register_Device
include blockdev.inc

mov     edi, OFFSET32 bdd       ; points to a BlockDev_Device_Descriptor

VXDcall BlockDev_Register_Device

jc      error                   ; error if carry set

The BlockDev_Register_Device service registers the specified Interrupt 13h device.

This service is available during initialization only.

Parameter	Description

bdd	Points to a BlockDev_Device_Descriptor structure containing information about the block device to be registered.

Exit

If the carry flag is clear, the block device is registered. Otherwise, the carry flag is set to indicate an error.

Comments

Virtual devices supporting block devices usually call this service to register their devices during the Sys_Critical_Init phase of device initialization.

This service returns an error if the Interrupt 13h device has already been registered by a virtual device or the Interrupt 13h drive has not been installed.

See Also

BlockDev_Device_Descriptor


BlockDev_Send_Command
include blockdev.inc

mov     edi, OFFSET32 bdd       ; points to a BlockDev_Device_Descriptor

mov     esi, OFFSET32 bcb       ; points to first BlockDev_Command_Block

VXDcall BlockDev_Send_Command

The BlockDev_Send_Command service sends one or more commands to the specified block device driver.

This service may be called at interrupt time.

Parameter	Description

bdd	Points to a BlockDev_Device_Descriptor structure containing information about the block device to receive the commands.

bcb	Points to the first BlockDev_Command_Block structure in a null-terminated list of commands to send to the block device.

Returns

This service has no return value.

Comments

The command status is returned to the callback procedure specified by the BD_CB_Cmd_Cplt_Proc field in the BlockDev_Command_Block structure.

This service enables interrupts.

Uses

Flags

See Also

BlockDev_Command_Block, BlockDev_Device_Descriptor


BlockDev_Synchronous_Command
include blockdev.inc

mov     ax,  CmdNum         ; command number

mov     edi, OFFSET32 bdd   ; points to a BlockDev_Device_Descriptor

VXDcall BlockDev_Synchronous_Command

The BlockDev_Synchronous_Command service sends a synchronous command to a specified block device.

Parameter	Description

CmdNum	Specifies a command number. It can be one of the following:

Value	Meaning

BD_SC_Get_Version	Retrieves the version number for the block device.

bdd	Points to a BlockDev_Device_Descriptor structure.

Returns

If the carry flag is clear, the EAX, EBX, ECX, EDX, ESI, EDI, and flags are modified as defined by the command. Otherwise, the carry flag is set and the AX register contains the following error value:

Value	Meaning

BD_SC_Err_Invalid_Cmd	Invalid synchronous command

Comments

Registers in addition to AX and EDI may be used as parameters for specific commands.

Uses

Registers defined by command and flags

See Also

BlockDev_Device_Descriptor


BlockDev_API_Hw_Detect_Start
include vmm.inc

include blockdev.inc

mov     ax, 1607h                   ; Device callout

mov     bx, BlockDev_Device_ID      ; Block device ID

mov     cx, BlockDev_API_Hw_Detect_Start

int     2Fh

The BlockDev_API_Hw_Detect_Start function notifies TSRs and MS-DOS device drivers that a virtual block device is performing hardware detection. This may, for example, disable a write-behind cache.

See Also

BlockDev_API_Hw_Detect_End


BlockDev_API_Hw_Detect_End
include vmm.inc

include blockdev.inc

mov     ax, 1607h                   ; Device callout

mov     bx, BlockDev_Device_ID      ; Block device ID

mov     cx, BlockDev_API_Hw_Detect_End

int     2Fh

The BlockDev_API_Hw_Detect_Start function notifies TSRs and MS-DOS device drivers that a virtual block device has completed hardware detection.

See Also

BlockDev_API_Hw_Detect_Start


BlockDev_API_Int13_Chain_Check
include vmm.inc

include blockdev.inc

mov     ax, 1607h                   ; Device callout

mov     bx, BlockDev_Device_ID      ; Block device ID

mov     cx, BlockDev_API_Int13_Chain_Check

int     2Fh

jcxz    okay                        ; zero if okay to load block device

The BlockDev_API_Int13_Chain_Check function notifies TSRs and MS-DOS device drivers that have hooked the ROM BIOS Interrupt 13h address that a block device is about to load. This notification gives the TSR or device driver a chance to cancel the loading.

Returns

The TSR or device driver sets the CX register to zero if it is permissible for block devices, such as WDCTRL, to load even though the MS-DOS Interrupt 13h chain has been modified.


BlockDev_Command_Block
include blockdev.inc

BlockDev_Command_Block  STRUC

BD_CB_Next              dd      ?

BD_CB_Command           dw      ?

BD_CB_Cmd_Status        dw      ?

BD_CB_Flags             dd      ?

BD_CB_Cmd_Cplt_Proc     dd      ?

BD_CB_Sector            dq      ?

BD_CB_Count             dd      ?

BD_CB_Buffer_Ptr        dd      ?

BD_CB_Reserved_Client   dd      ?

BD_CB_Reserved_BlockDev dd      ?

BD_CB_Reserved_FastDisk dd      ?

BlockDev_Command_Block  ENDS

The BlockDev_Command_Block structure contains information about a block device command.

Member	Description

BD_CB_Next	Points to the next command in the command list.

BD_CB_Command	Specifies the command to carry out. It can be one of the following values:

Value	Meaning

BDC_Read	Read from device

BDC_Write	Write to device

BDC_Verify	Verify read or write

BDC_Cancel	Cancel command

Command values in the range 8000h through 0FFFFh are reserved for device-specific commands.

BD_CB_Cmd_Status	Specifies the status of the command. It can be one of the following values:

Value	Meaning

BDS_Success	Command completed successfully

BDS_Success_With_Retries	Command completed successfully after repetition

BDS_Success_With_ECC	Command completed successfully after error correction

BDS_Invalid_Sector_Number	Invalid sector number

BDS_Canceled	Command was canceled

BDS_Cmd_In_Progress	Can't cancel command in progress

BDS_Invalid_Cmd_Ptr	Cancel of invalid command pointer

BDS_Media_Error	Read or write failed

BDS_Device_Error	Device or adapter failed

BDS_Invalid_Command	Invalid command

All values below BDS_First_Error_Code (10h) imply successful completion; error values are greater than or equal to BDS_First_Error_Code.

BD_CB_Flags	Specifies additional actions to take when carrying out the command. This field can be a combination of the following values:

Value	Meaning

BDCF_High_Priority	High priority

BDCF_Scatter_Gather	Scatter or gather

BDCF_Dont_Cache	Noncached command

BD_CB_Cmd_Cplt_Proc	Points to the command-completion callback procedure.

BD_CB_Sector	Specifies the count of sectors for the block device.

BD_CB_Count	Specifies the count.

BD_CB_Buffer_Ptr	Points to the buffer.

BD_CB_Reserved_Client	Reserved.

BD_CB_Reserved_BlockDev	Reserved.

BD_CB_Reserved_FastDisk	Reserved.


BlockDev_Device_Descriptor
include blockdev.inc

BlockDev_Device_Descriptor STRUC

BDD_Next                dd      ?

BDD_BD_Major_Ver        db      BD_Major_Version

BDD_BD_Minor_Ver        db      BD_Minor_Version

BDD_Device_Type         db      ?

BDD_Int_13h_Number      db      ?

BDD_Flags               dd      ?

BDD_Name_Ptr            dd      ?

BDD_Max_Sector          dq      ?

BDD_Sector_Size         dd      ?

BDD_Num_Heads           dd      ?

BDD_Num_Cylinders       dd      ?

BDD_Num_Sec_Per_Track   dd      ?

BDD_Sync_Cmd_Proc       dd      ?

BDD_Command_Proc        dd      ?

BDD_Hw_Int_Proc         dd      0

BDD_Reserved_BlockDev   db      BD_Priv_Data_Size dup (?)

BlockDev_Device_Descriptor ENDS

The BlockDev_Device_Descriptor structure contains information about the block device.

Member	Description

BDD_Next	Points to the next BlockDev_Device_Descriptor structure in the list.

BDD_BD_Major_Ver	Specifies the major version number. It is 03h for version 3.1.

BDD_BD_Minor_Ver	Specifies the minor version number. It is 0Ah for version 3.1.

BDD_Device_Type	Specifies the type of hardware device. It can be one of the following values:

Value	Meaning

BDT_360K_5_Inch_Floppy	5.25 inch, 360 kilobyte floppy drive

BDT_1200K_5_Inch_Floppy	5.25 inch, 1.2 megabyte floppy drive

BDT_720K_3_Inch_Floppy	3.5 inch, 720 kilobyte floppy drive

BDT_Single_Dens_8_Inch	8 inch, single density floppy drive

BDT_Double_Dens_8_Inch	8 inch, double density floppy drive

BDT_Fixed_Disk	Hard disk drive

BDT_Tape_Drive	Tape drive

BDT_Other	Other storage media

BDD_Int_13h_Number	Specifies the Interrupt 13h number.

BDD_Flags	Specifies the device flags. It can be one or more of the following values:

Value	Meaning

BDF_Int13_Drive	Interrupt 13h drive

BDF_Writeable	Writable media

BDF_Removable	Removable media

BDF_Remote	Remote device

BDF_Serial_Cmd	Serial commands

BDF_Cache	Cached device

BDD_Name_Ptr	Points to a null-terminated string specifying the name of the block device.

BDD_Max_Sector	Specifies the maximum number of sectors for the block device.

BDD_Sector_Size	Specifies the size (in bytes) of each sector.

BDD_Num_Heads	Specifies the number of head for the block device.

BDD_Num_Cylinders	Specifies the number of cylinders for the block device.

BDD_Num_Sec_Per_Track	Specifies the number of sectors in each track of the block device.

BDD_Sync_Cmd_Proc	Points to the synchronous command procedure for the block device.

BDD_Command_Proc	Points to the command procedure for the block device.

BDD_Hw_Int_Proc	Points to the hardware interrupt handler for the block device.

BDD_Reserved_BlockDev	Reserved.

See Also

BlockDev_Command_Complete


Virtual Communications Device

VCD_Get_Focus	Returns focus owner

VCD_Get_Version	Returns version number

VCD_Set_Port_Global	Enables or disables global port

VCD_Virtualize_Port	Virtualizes a COM port


VCD_Get_Focus
include vcd.inc

VxDcall VCD_Get_Focus

The VCD_Get_Focus service returns the virtual machine handle of the current owner of a COM port. Focus can be set with a Set_Device_Focus control message sent using the System_Control service and specifying the VCD device.

Parameter	Description

EAX	Specifies the hardware COM port number. It must be in the range 1 to 4.

Returns

If the carry flag is clear, the EBX register contains virtual machine handle or zero if there is no owner.

The carry flag is set if the port is not available.

Uses

EBX, Flags


VCD_Get_Version
include vcd.inc

VxDcall VCD_Get_Version

The VCD_Get_Version service returns the VCD version number.

This service has no parameters.

Returns

If the carry flag is clear, the EAX register contains the version number. Otherwise, the VCD is not installed and VCD pages are not allocated.

Uses

EAX, Flags


VCD_Set_Port_Global
include vcd.inc

VxDcall VCD_Set_Port_Global

The VCD_Set_Port_Global service enables or disables the global handling of a COM port between multiple virtual machines. When a port is declared to be a global port, then no contention detection is performed, and no I/O ports are trapped.

This service is provided mainly for a COM port mouse, or other serial device, where a separate virtual device handles the arbitration of the port and its interrupts. A Set_Device_Focus control message sent using the System_Control service can specify which virtual machine should receive interrupt requests and VCD_Get_Focus returns the current owner of a port.

Parameter	Description

EAX	Specifies the hardware COM port number. It must be in the range from 1 to 4.

EDX	Specifies whether the port is global (zero) or local (nonzero).

Returns

The carry flag is clear if the service is successful. Otherwise, the carry flag is set if the port is not available.

Uses

Flags


VCD_Virtualize_Port
include vcd.inc

VxDcall VCD_Virtualize_Port

The VCD_Virtualize_Port service virtualizes a COM port. This service allows additional virtual devices to provide enhanced capabilities to COM port virtualization. An example virtual device is one which buffers high speed input data, and then simulates interrupts into the owner virtual machine, at a slower rate, so that the virtual machine can keep up with the data without losing input.

This service can only be called during processing of the Sys_Critical_Init message.

Parameter	Description

EAX	Specifies the port number (1, 2, 3, or 4).

EBX	Specifies the operation flags. It is 00000001h if the IRQ is sharable. All other values are reserved.

ECX	Specifies the number of extra bytes needed in the VCD_COM_Struc structure.

EDX	Specifies the number of extra bytes needed in the VCD_CB_Struc structure.

ESI	Points to the VCD_ProcList_Struc a structure which contains a list of callback procedures. The VCD saves the pointer to this structure, so it must be placed in the VxD_DATA_SEG segment.

Returns

If the carry is clear, the port can be virtualized and the EAX register contains the COM handle which points to the COM structure having the extra data allocated at its end.

Otherwise, the carry flag is set if the port is not available and the EAX register contains one of the following values:

Value	Meaning

0	Port does not exist

1	Port already virtualized

Comments

Callback procedures are provided in the list pointed to by ESI.

The VPS_Control_Proc callback is called when the virtualization state changes for a COM port. Currently the only call is for ownership changes.

EAX     ; VCD_Control_Set_Owner

EBX     ; virtual machine handle of new owner or 0,if virtualization

        ; handled by a different device

EDX     ; virtual machine handle of previous owner or 0

ESI     ; points to a VCD_COM_Struc

On entry, when the EBX register specifies a new owner, port trapping will be enabled for all I/O ports of the COM adapter. The control procedure can disable any I/O trapping that it desires.

The IRQ virtualization procedures are the same as if the virtual device virtualized the IRQ directly using the VPICD, except that ESI points to the VCD_COM_Struc structure on entry. See the VPICD documentation for actual entry parameters and return values.

EAX     ; IRQ handle

EBX     ; virtual machine handle

ESI     ; points to a VCD_COM_Struc

The following callbacks have default actions, if the callback offset is set to 0:

Callback	Default Action

VPS_Hw_Int_Proc	Assign an owner to the current virtual machine if not owned, and request an interrupt in the owner's virtual machine.

VPS_Virt_Int_Proc	Not virtualized.

VPS_EOI_Proc	Physically EOI and clear interrupt request.

VPS_Mask_Change_Proc	Assign the owner to the current virtual machine if not owned.

VPS_IRET_Proc	Not virtualized.

The following callbacks deal with I/O for ports that have trapping enabled while the virtualizing virtual device owns a COM port.

VPS_In_RxTxB

VPS_Out_RxTxB

VPS_In_IER

VPS_Out_IER

VPS_In_IIR

VPS_Out_IIR

VPS_In_LCR

VPS_Out_LCR

VPS_In_MCR

VPS_Out_MCR

VPS_In_LSR

VPS_Out_LSR

VPS_In_MSR

VPS_Out_MSR

These callbacks have the following parameters:

EBX     ; virtual machine handle

ESI     ; points to a VCD_COM_Struc

EDX     ; port number

ECX     ; Byte_Input or Byte_Output value

AL      ; output data if ECX is Byte_Output

These procedures should return the AL register set to the input data if the ECX register is equal to the Byte_Input value.

Uses

EAX, Flags


Virtual Display Device

VDD_Clear_Mod	Clear change state

VDD_Free_Grab	Releases screen-grab memory

VDD_Free_Mem	Releases screen memory

VDD_Get_GrabRtn	Returns address of screen grabber

VDD_Get_GrbMem	Returns address of screen-grab memory

VDD_Get_GrbState	Returns screen-grab state

VDD_Get_Mem	Returns address of screen memory

VDD_Get_Mod	Returns changes in video state

VDD_Get_ModTime	Indicates video activity

VDD_Get_State	Returns state of virtual machine

VDD_Get_Version	Returns version number

VDD_Hide_Cursor	Hides or shows cursor

VDD_Msg_BakColor	Sets the background color for messages

VDD_Msg_ClrScrn	Clears screen for message

VDD_Msg_ForColor	Sets foreground color for message

VDD_Msg_SetCursPos	Sets cursor position for message

VDD_Msg_TextOut	Displays text

VDD_PIF_State	Specifies PIF settings

VDD_Query_Access	Specifies whether video memory is accessible

VDD_Set_HCurTrk	Tracks cursor in window

VDD_Set_VMType	Specifies virtual machine type

VDD_Unlock_APP	Unlocks application from grabber


VDD_Clear_Mod
include vdd.inc

VxDcall VDD_Clear_Mod

The VDD_Clear_Mod service clears the change state of a virtual machine.

Parameter	Description

EDX	Specifies the system virtual machine handle.

EBX	Specifies the handle of the virtual machine to clear the change state for.

EDI	Specifies the VDD control block pointer.

EBP	Points to the Client_Reg_Struc structure for the virtual machine.

Client_EBX	Specifies the virtual machine handle.

Returns

The carry flag is set if an invalid virtual machine handle is specified. Otherwise, this service has no return value.

Comments

This service allows proper text scrolling if an application runs between calls to the VDD_Get_Mod and VDD_Clear_Mod services.

This service assumes that VDD_Clear_Mod is called twice when the VDD sends a scroll event to 386 enhanced mode grabber; once in the TextScroll function and again in the UpdateScreen function.

If an application has accessed pages since the last call to the VDD_Get_Mod service and there is a scroll event generated in the previous VDD_Get_Mod, the service sets the fVDD_UpdAll1Bit value in VDD_Flags and transfers main memory to copy memory. The VDD_Clear_Mod service clears the fVDD_UpdAll1Bit value and sets fVDD_UpdAll2Bit. The VDD_State_Query service returns changes if fVDD_UpdAll2Bit is set. Since fVDD_UpdAll2Bit is set, the VDD_Mod_Text service returns the entire screen changed (no scrolls) and the VDD_Clear_Mod service clears the fVDD_UpdAll2Bit value and updates the copy memory.

If application accessed pages since the last VDD_Get_Mod and there was no scroll event in the previous VDD_Get_Mod, the copy memory is not updated.

Uses

Flags


VDD_Free_Grab
include vdd.inc

VxDcall VDD_Free_Grab

The VDD_Free_Grab service releases the copy of the video memory that was allocated when a screen grab was done.

Parameter	Description

EDX	Specifies the system virtual machine handle.

EBX	Specifies the handle of the virtual machine to release the memory for.

EDI	Specifies the VDD control block pointer.

EDI	Specifies the VDD control block pointer.

EBP	Points to the Client_Reg_Struc structure for the virtual machine.

Client_EBX	Specifies the virtual machine handle.

Returns

This service has no return value.

Uses

Flags


VDD_Free_Mem
include vdd.inc

VxDcall VDD_Free_Mem

The VDD_Free_Mem service releases the scheduling freeze caused by a previous call to the VDD_Get_Mem service.

Parameter	Description

EDX	Specifies the system virtual machine handle.

EBX	Specifies the handle of the virtual machine to release the freeze for.

EDI	Specifies the VDD control block pointer.

EBP	Points to the Client_Reg_Struc structure for the virtual machine.

Client_EBX	Specifies the virtual machine handle.

Returns

The carry flag is set if an invalid virtual machine handle is specified. Otherwise, this service has no return value.

Uses

Flags

See Also

VDD_Get_Mem


VDD_Get_GrabRtn
include vdd.inc

VxDcall VDD_Get_GrabRtn

The VDD_Get_GrabRtn service returns address of video grab routine. The grab routine is called by the virtual shell device when the appropriate hot key is pressed by the user. It makes a copy of the visible screen and controller state of the current virtual machine. The copy is accessible using the VDD_Get_GrbState and VDD_Get_GrbMem services.

This service has no parameters.

Returns

The ESI register contains the address of the grab routine.

Uses

Flags, ESI

See Also

VDD_Get_GrbMem, VDD_Get_GrbState


VDD_Get_GrbMem
include vdd.inc

VxDcall VDD_Get_GrbMem

The VDD_Get_GrbMem service return the flat address and allocation bitmap for virtual machine's video memory. This service returns the address of the copy of the memory that was made by the grab routine.

Parameter	Description

EDX	Specifies the system virtual machine handle.

EBX	Specifies the handle of the virtual machine to retrieve the memory for.

EDI	Specifies the VDD control block pointer.

EBP	Points to the Client_Reg_Struc structure for the virtual machine.

Client_EBX	Specifies the virtual machine handle.

Client_ES	Specifies the selector identifying the segment containing the buffer to receive the VDA_Mem_State.

Client_EDI	Specifies the address of the buffer to receive the VDA_Mem_State.

Client_CX	Specifies the size of the buffer to hold the VDA_Mem_State. This is for debugging only.

Returns

The Client_CX register contains the number of bytes copied to the buffer. Otherwise, it is zero to indicate an error such as the buffer is too small, an invalid selector, or a call to VDD_Get_GrbMem when no grab is active.

Comments

The allocation of memory to the bitmap is dynamic. The grabber must call this service each time it accesses the memory.

Uses

Flags


VDD_Get_GrbState
include vdd.inc

VxDcall VDD_Get_GrbState

The VDD_Get_GrbState service returns the state of the video adapter for the specified virtual machine at the point when the VDD_GrabRtn was called.

This service is called by the 386 enhanced mode grabber.

Parameter	Description

EDX	Specifies the system virtual machine handle.

EBX	Specifies the handle of the virtual machine to retrieve the state for.

EDI	Specifies the VDD control block pointer.

EBP	Points to the Client_Reg_Struc structure for the virtual machine.

Client_EBX	Specifies the virtual machine handle.

Client_ES	Specifies the selector identifying the segment containing the buffer to receive the state.

Client_EDI	Specifies the address of the buffer to receive the state.

Client_CX	Specifies the size of the buffer to hold the state. This is for debugging only.

Returns

The Client_CX register contains the size of the structure returned by the service (for debugging only). The service returns zero to indicate an error.

Comments

This service returns a video state structure. See the VDD.INC file for the structure definition.

Uses

Flags, Client_CX


VDD_Get_Mem
include vdd.inc

VxDcall VDD_Get_Mem

The VDD_Get_Mem service returns the flat address and allocation bitmap for the specified virtual machine's video memory. This service returns the main video-save memory and boosts the scheduling priority of the system virtual machine.

Parameter	Description

EDX	Specifies the system virtual machine handle.

EBX	Specifies the handle of the virtual machine to retrieve the memory for.

EDI	Specifies the VDD control block pointer.

EBP	Points to the Client_Reg_Struc structure for the virtual machine.

Client_EBX	Specifies the virtual machine handle.

Client_ES	Specifies the selector identifying the segment containing the buffer to receive the VDA_Mem_State.

Client_EDI	Specifies the address of the buffer to receive the VDA_Mem_State.

Client_CX	Specifies the size of the buffer to hold the VDA_Mem_State. This is for debugging only.

Returns

The Client_CX register contains the number of bytes copied to the buffer. Otherwise, it is zero to indicate an error such as the buffer is too small or an invalid selector.

Comments

To prevent memory from changing between calls to the VDD_Get_Mem and VDD_Free_Mem services, this service boosts the system virtual machine's priority using the Low_Priority_Device_Boost value. This inhibits normal scheduling but does not hamper scheduling of virtual machine's to handle events such as interrupts.

The allocation of memory to the bitmap is dynamic. The grabber must call this service each time it accesses the memory.

A call to the VDD_Get_Mem service must be followed by a call to the VDD_Free_Mem service as soon as possible. No other virtual machine will be scheduled until the call to VDD_Free_Mem is made.

Uses

Flags


VDD_Get_Mod
include vdd.inc

VxDcall VDD_Get_Mod

The VDD_Get_Mod service returns changes in a virtual machine's video state. The changes are passed to the grabber in a buffer that includes a flag indicating what kind of changes occurred and what type of a memory change list follows. The flag is followed by a count of memory-change-list entries and the change list itself.

This service returns cumulative changes until the VDD_Clear_Mod service is called.

Parameter	Description

EDX	Specifies the system virtual machine handle.

EBX	Specifies the handle of the virtual machine to retrieve the change list for.

EDI	Specifies the VDD control block pointer.

EBP	Points to the Client_Reg_Struc structure for the virtual machine.

Client_EBX	Specifies the virtual machine handle.

Client_ES	Specifies the selector identifying the segment containing the buffer to receive the change list.

Client_EDI	Specifies the address of the buffer to receive the change list.

Client_CX	Specifies the size of the buffer to receive the change list. This is for debugging only.

Returns

The Client_CX register contains the size of structure returned by the service (for debugging only). The service returns zero to indicate an error.

Uses

Flags, Client_CX


VDD_Get_ModTime
include vdd.inc

VxDcall VDD_Get_ModTime

The VDD_Get_ModTime service specifies whether any video activity has occurred. The virtual poll device uses it to determine if the virtual machine is idle.

Parameter	Description

EBX	Specifies the virtual machine handle.

Returns

The EAX register contains the system time at last video modification.

Uses

Flags, EAX


VDD_Get_State
include vdd.inc

VxDcall VDD_Get_State

The VDD_Get_State service returns the current state of the virtual machine. This service should be called after a call to the VDD_Get_Mem service buts before calling the VDD_Free_Mem service.

This service is called by the grabber.

Parameter	Description

EDX	Specifies the system virtual machine handle.

EBX	Specifies the handle of the virtual machine to retrieve the change list for.

EDI	Specifies the VDD control block pointer.

EBP	Points to the Client_Reg_Struc structure for the virtual machine.

Client_EBX	Specifies the virtual machine handle.

Client_ES	Specifies the selector identifying the segment containing the buffer to receive the state.

Client_EDI	Specifies the address of the buffer to receive the state.

Client_CX	Specifies the size of the buffer to receive the state. This is for debugging only.

Returns

The Client_CX register contains the size of structure returned by the service (for debugging only). The service returns zero to indicate an error.

Comments

This service returns a video state structure. See the VDD.INC file for the structure definition.

Uses

Flags, Client_CX


VDD_Get_Version
include vdd.inc

VxDcall VDD_Get_Version

The VDD_Get_Version service returns the VDD version number and device identifier.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

The ESI register contains the address of the 8-byte identifier string for the VDD.

Uses

Fags, AX, ESI


VDD_Hide_Cursor
include vdd.inc

VxDcall VDD_Hide_Cursor

The VDD_Hide_Cursor service sets or clears the hide-cursor flag. The virtual mouse device uses this service to turn on and off the hardware cursor such as when the virtual machine is windowed.

Parameter	Description

EAX	Specifies whether the cursor should be hidden (nonzero) or displayed (zero).

EBX	Specifies a pointer to the control block.

Returns

This service has no return value.

Uses

Flags


VDD_Msg_BakColor
include vdd.inc

VxDcall VDD_Msg_BakColor

The VDD_Msg_BakColor service sets up the background attribute for messages displayed when in message mode.

Parameter	Description

EAX	Specifies the color. For EGA/VGA driver, this parameter is a text mode attribute.

EBX	Specifies the virtual machine handle.

Returns

This service has no return value.

Comments

A virtual device that uses this service must issue a Begin_Message_Mode control message before calling this service.

Uses

Flags


VDD_Msg_ClrScrn
include vdd.inc

VxDcall VDD_Msg_ClrScrn

The VDD_Msg_ClrScrn service initializes the screen for messages displayed when in message mode. If the focus virtual machine is the current virtual machine, this service clears the screen immediately. Otherwise, it initializes the screen when the focus changes.

The virtual shell device uses this service.

Parameter	Description

EBX	Specifies the virtual machine handle.

EAX	Specifies the background attribute.

Returns

The EAX register contains the width in columns.

The EDX register contains the height in rows.

Comments

A virtual device that uses this service must issue a Begin_Message_Mode control message before calling this service.

Uses

Flags, EAX, EDX


VDD_Msg_ForColor
include vdd.inc

VxDcall VDD_Msg_ForColor

The VDD_Msg_ForColor service sets the foreground attribute for messages displayed when in message mode.

Parameter	Description

EAX	Specifies the color. For EGA/VGA drivers, this parameter is a text mode attribute.

EBX	Specifies the virtual machine handle.

Returns

This service has no return value.

Comments

A virtual device that uses this service must issue a Begin_Message_Mode control message before calling this service.

Uses

Flags


VDD_Msg_SetCursPos
include vdd.inc

VxDcall VDD_Msg_SetCursPos

The VDD_Msg_SetCursPos service sets the cursor position for messages displayed when in message mode.

Parameter	Description

EAX	Specifies the row position.

EDX	Specifies the column position.

EBX	Specifies the virtual machine handle.

Returns

This service has no return value.

Comments

A virtual device that uses this service must issue a Begin_Message_Mode control message before calling this service.

Uses

Flags


VDD_Msg_TextOut
include vdd.inc

VxDcall VDD_Msg_TextOut

The VDD_Msg_TextOut service writes the specified text to the screen using the foreground and background colors specified by the VDD_Msg_BakColor and VDD_Msg_ForColor services.

Parameter	Description

ESI	Specifies the address of the string to display.

ECX	Specifies the length in bytes of the string.

EAX	Specifies the row position for the start of the displayed string.

EDX	Specifies the column position for the start of the displayed string.

EBX	Specifies the virtual machine handle

Returns

This service has no return value.

Comments

A virtual device that uses this service must issue a Begin_Message_Mode control message before calling this service.

Uses

Flags

See Also

VDD_Msg_BakColor, VDD_Msg_ForColor


VDD_PIF_State
include vdd.inc

VxDcall VDD_PIF_State

The VDD_PIF_State service informs the VDD about PIF bits for virtual machine just created.

Parameter	Description

EBX	Specifies the virtual machine handle.

AX	Specifies the PIF bits.

Returns

This service has no return value.

Uses

Flags


VDD_Query_Access
include vdd.inc

VxDcall VDD_Query_Access

The VDD_Query_Access service specifies whether video memory can be accessed. Virtual devices that call software in the virtual machine use this service to determine whether a video display error will occur if the software attempts to access video memory.

Parameter	Description

EBX	Specifies the address of the control block.

Returns

The carry flag is clear if a virtual device can access video memory.

Comments

The virtual device should call this service just before returning to the virtual machine such as while processing a virtual machine event. If the video memory cannot be accessed, the virtual device should avoid calling software that may attempt access even if not calling the software causes another error, such as leaving the mouse cursor on when the virtual machine runs in a window.

Uses

Flags


VDD_Set_HCurTrk
include vdd.inc

VxDcall VDD_Set_HCurTrk

The VDD_Set_HCurTrk service sets the flag passed to VMDOSAPP indicating that VMDOSAPP should maintain cursor position within display window for this application. The keyboard driver calls this service when a keyboard interrupt is simulated into a virtual machine.

Parameter	Description

EBX	Specifies the virtual machine handle.

Returns

This service has no return value.

Uses

Flags


VDD_Set_VMType
include vdd.inc

VxDcall VDD_Set_VMType

The VDD_Set_VMType service informs the VDD of a virtual machine's type. The system calls this service prior to running the virtual machine and each time any of the virtual machine parameters are modified.

Parameter	Description

EAX	Specifies the state flag. This parameter is nonzero if the virtual machine is running in a window.

EBX	Specifies the virtual machine handle. This handle can be used to examine the virtual machine status flags such as the exclusive and background flags.

Returns

This service has no return value.

Comments

For a system critical Set_Focus this service may not be called before the Set_Focus. In that case, the VDD is responsible for doing an implied call to the VDD_Set_VMType service.

Uses

Flags


VDD_Unlock_APP
include vdd.inc

VxDcall VDD_Unlock_APP

The VDD_Unlock_APP service unlocks the Windowed OLDAPP from the grabber.

This service is also called from the VDD_Free_Mem service.

Parameter	Description

EDX	Specifies the system virtual machine handle.

EBX	Specifies the handle of the virtual machine running the application to unlock.

EDI	Specifies the VDD control block pointer.

EBP	Points to the Client_Reg_Struc structure for the virtual machine.

Client_EBX	Specifies the virtual machine handle.

Returns

This service has no return value.

Uses

EAX, Flags


Virtual DMA Device

VDMAD_Copy_From_Buffer	Copy from DMA buffer

VDMAD_Copy_To_Buffer	Copy into DMA buffer

VDMAD_Default_Handler	Sets default DMA handler

VDMAD_Disable_Translation	Disables automatic translation

VDMAD_Enable_Translation	Enables automatic translation

VDMAD_Get_EISA_Adr_Mode	Returns EISA extended mode

VDMAD_Get_Region_Info	Returns information about region

VDMAD_Get_Version	Returns version number

VDMAD_Get_Virt_State	Returns state of DMA channel

VDMAD_Lock_DMA_Region	Locks a region for DMA transfer

VDMAD_Mask_Channel	Masks a channel to prevent transfers

VDMAD_Release_Buffer	Releases a DMA buffer

VDMAD_Request_Buffer	Requests a DMA buffer

VDMAD_Reserve_Buffer_Space	Allocates DMA buffer

VDMAD_Scatter_Lock	Locks pages and returns locations

VDMAD_Scatter_Unlock	Unlocks pages

VDMAD_Set_EISA_Adr_Mode	Sets EISA extended mode

VDMAD_Set_Phys_State	Programs controller state

VDMAD_Set_Region_Info	Sets region information

VDMAD_Set_Virt_State	Sets the virtual state for a DMA channel

VDMAD_Unlock_DMA_Region	Unlocks DMA region

VDMAD_UnMask_Channel	Unmasks DMA channel

VDMAD_Virtualize_Channel	Virtualizes a channel


VDMAD_Copy_From_Buffer
include vdmad.inc

VxDcall VDMAD_Copy_From_Buffer

The VDMAD_Copy_From_Buffer service allows another device to copy data from the VDMAD buffer to the actual DMA region associated with the buffer. This service is called after the VDMAD_Request_Buffer service, after a memory write transfer and before the VDMAD_Release_Buffer service.

Parameter	Description

EBX	Specifies the buffer identifier.

ESI	Specifies the region linear.

EDI	Specifies the offset within the buffer to the start of copying.

ECX	Specifies the size of the buffer.

Returns

The carry flag is clear if the data is copied from buffer into DMA region. Otherwise, the carry flag is set and the AL register contains one of the following error values:

Value	Meaning

0Ah	DMA_Invalid_Buffer: invalid buffer id supplied

0Bh	DMA_Copy_Out_Range: (ESI + ECX) is greater than buffer size

Uses

EAX, Flags


VDMAD_Copy_To_Buffer
include vdmad.inc

VxDcall VDMAD_Copy_To_Buffer

The VDMAD_Copy_To_Buffer service allows another device to copy data into the VDMAD buffer from the actual DMA region associated with the buffer. This service is called after the VDMAD_Request_Buffer service and before starting a memory read transfer.

Parameter	Description

EBX	Specifies the buffer identifier.

ESI	Specifies the region linear.

EDI	Specifies the offset within the buffer to the start of copying.

ECX	Specifies the size of the buffer.

Returns

The carry flag is clear if the data is copied from the DMA region into the buffer. Otherwise, the carry flag is set and the AL register contains one of the following error values:

Value	Meaning

0Ah	DMA_Invalid_Buffer: invalid buffer id supplied

0Bh	DMA_Copy_Out_Range: (ESI + ECX) is greater than buffer size

Uses

EAX, Flags


VDMAD_Default_Handler
include vdmad.inc

VxDcall VDMAD_Default_Handler

The VDMAD_Default_Handler service specifies the default DMA channel I/O callback procedure. This procedure receives notifications of virtual state changes and handles setting up the physical state to start DMA transfers.

Parameter	Description

EAX	Specifies the DMA handle.

EBX	Specifies the virtual machine handle.

Returns

This service has no return value.

Uses

All


VDMAD_Disable_Translation
include vdmad.inc

VxDcall VDMAD_Disable_Translation

The VDMAD_Disable_Translation service disables the automatic translation done for the standard DMA channels. It is necessary if a V86 application or driver or a PM application uses the DMA services through Interrupt 4Bh to determine actual physical addresses for DMA transfers. A disable count is maintained, so a matching call to VDMAD_Enable_Translation is required for each call to this service to re-enable translation.

Parameter	Description

EAX	Specifies the DMA handle.

EBX	Specifies the virtual machine handle.

Returns

The carry flag is clear is automatic translation is disabled for the channel. Otherwise, the carry flag is set if the disable count overflowed.

Uses

Flags


VDMAD_Enable_Translation
include vdmad.inc

VxDcall VDMAD_Enable_Translation

The VDMAD_Enable_Translation service decrements the disable count associated with a standard DMA channel. If the disable count goes to 0, the automatic translation is re-enabled.

Parameter	Description

EAX	Specifies the DMA handle.

EBX	Specifies the virtual machine handle.

Returns

The carry flag is clear if the service is successful. The zero flag is clear if automatic translation is re-enabled. Otherwise, the carry flag is set if the irtual device attempted to enable when translation was already enabled.

Uses

Flags

See Also

VDMAD_Disable_Translation


VDMAD_Get_EISA_Adr_Mode
include vdmad.inc

VxDcall VDMAD_Get_EISA_Adr_Mode

The VDMAD_Get_EISA_Adr_Mode service returns the EISA extended mode.

Parameter	Description

EAX	Specifies the channel number. It must be in the range 0 to 7.

EBX	Specifies the DMA handle.

Returns

The CL register contains one of the following values:

Value	Meaning

0	8-bit I/O, with count in bytes

1	16-bit I/O, with count in words and adr shifted

2	32-bit I/O, with count in bytes

3	16-bit I/O, with count in bytes

Comments

The hardware does not allow for reading the extended mode for a channel, so VDMAD defaults to the ISA defaults (channels 0-3 are byte channels and 5-7 are word channels with word addresses and counts). An SYSTEM.INI setting can specify an alternate setting.

Uses

ECX, Flags


VDMAD_Get_Region_Info
include vdmad.inc

VxDcall VDMAD_Get_Region_Info

The VDMAD_Get_Region_Info service returns information about the current region assigned to a DMA handle. This information can be used by a handler to call following services:

VDMAD_Unlock_DMA_Region

VDMAD_Release_Buffer

VDMAD_Copy_To_Buffer

VDMAD_Copy_From_Buffer

Parameter	Description

EAX	Specifies the DMA handle.

Returns

The BX, ESI, and ECX registers contain the following information:

Register	Description

BL	Specifies the buffer identifier.

BH	Specifies whether pages are locked (zero is not locked, nonzero is locked).

ESI	Specifies the region linear.

ECX	Specifies the size in bytes.

Uses

EBX, ECX, ESI


VDMAD_Get_Version
include vdmad.inc

VxDcall VDMAD_Get_Version

The VDMAD_Get_Version service returns the version number of the virtual DMA device.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

The ECX register contains the buffer size in bytes. It is zero if the buffer is not allocated. A buffer is not available until the Init_Complete message.

The carry flag is clear.

Uses

EAX, ECX, Flags


VDMAD_Get_Virt_State
include vdmad.inc

VxDcall VDMAD_Get_Virt_State

The VDMAD_Get_Virt_State service allows a channel owner to determine the current virtual state of the channel. The virtual state consists of all the information necessary to physically program the DMA channel for a DMA transfer (linear address of target region, byte length of region, mode of transfer, and state of mask bit and software request bit)

Parameter	Description

EAX	Specifies the DMA handle.

EBX	Specifies the virtual machine handle.

Returns

If translation is enabled, the ESI register contains the high linear address of the user's DMA region. The high linear address is used so that the DMA can proceed even if a different virtual machine is actually running at the time of the transfer.

If translation is not enabled, the ESI register contains the physical byte address programmed (shifted left 1, for word ports).

The ECX register contains count in bytes.

The DL register contains the mode. This is the same as the 8237 mode byte with channel number removed and the following DMA_masked and DMA_requested values set as appropriate:

Value	Meaning

DMA_masked	Channel masked and not ready for a transfer

DMA_requested	Software request flag set

The DH register contains the extended mode (ignored on non-PS2 machines that do not have extended DMA capabilities).

Uses

ESI, ECX, EDX, Flags


VDMAD_Lock_DMA_Region
include vdmad.inc

VxDcall VDMAD_Lock_DMA_Region

The VDMAD_Lock_DMA_Region service attempts to lock a region of memory for a DMA transfer. It is called before a DMA transfer is started, that is, before the physical state is set for a channel and before it is unmasked.

Parameter	Description

ESI	Specifies the linear address of the actual DMA region.

ECX	Specifies the numbers of bytes in the DMA region.

DL	Specifies the alignment. This parameter can be one of the following values:

Value	Meaning

1	region must be aligned on 64K page boundary

2	region must be aligned on 128K page boundary

Returns

The carry flag is set if the lock failed. The ECX register contains the number of bytes that are lockable in the region (starting from ESI), and the AL registers contains one of the following error values:

Value	Meaning

1	DMA_Not_Contiguous: region not contiguous

2	DMA_Not_Aligned: region crossed physical alignment boundary

3	DMA_Lock_Failed: unable to lock pages

The carry flag is clear if the lock is successful. The EDX register contains the physical address of the DMA region the region has been locked.

Comments

The service first verifies that the region is mapped to contiguous pages of physical memory, then it determines whether the region results in a DMA bank (page) wrap.

On AT class machines each channel has a base address register and a page address register. The base address register is incremented after each byte or word transferred. If the increment of this 16-bit register results in the roll over from FFFFh to 0, then the transfer wraps to the start of the DMA bank because the page register is not updated. Normally MS-DOS watches for this condition and adjusts Interrupt 13h parameters to split transfers to avoid this wrap, but MS-DOS does not account for the difference between linear and physical addresses under Windows, so VDMAD checks again to prevent wrap from occurring.

If these checks pass, the service calls the memory manager to lock the physical pages.

This service does not check to see if the region is within some physical maximum constraint. If the region is lockable, then it locks the memory, and it is up to the caller to check to see if the physical region is acceptable. If the region is not acceptable, then the caller should unlock the region and perform a buffered DMA transfer.

Uses

EAX, ECX, EDX, Flags


VDMAD_Mask_Channel
include vdmad.inc

VxDcall VDMAD_Mask_Channel

The VDMAD_Mask_Channel service physically masks a channel so that it will not attempt any further DMA transfers.

Parameter	Description

EAX	Specifies the DMA handle.

Returns

This service has no return value.

Uses

Flags


VDMAD_Release_Buffer
include vdmad.inc

VxDcall VDMAD_Release_Buffer

The VDMAD_Release_Buffer service releases the VDMAD buffer assigned to a DMA channel from a previous call to the VDMAD_Request_Buffer service. This service exits from a critical section and the DMA buffer becomes available for other users. Any data in the buffer is not automatically copied, so the VDMAD_Copy_From_Buffer service must be called if the data is important.

Parameter	Description

EBX	Specifies the buffer identifier.

Returns

The carry flag is clear if the buffer is released. Otherwise, the carry flag is set to indicate an invalid buffer identifier.

Uses

Flags


VDMAD_Request_Buffer
include vdmad.inc

VxDcall VDMAD_Request_Buffer

The VDMAD_Request_Buffer service reserves the DMA buffer for a DMA transfer.

Parameter	Description

ESI	Specifies the linear address of the actual DMA region.

ECX	Specifies the number of bytes in the DMA region.

Returns

The carry flag is clear if the service is successful. The EBX register contains the buffer identifier and the EDX register contains the physical address of the buffer.

Otherwise, the carry flag is set and the AL register contains one of the following error values:

Value	Meaning

5	DMA_Buffer_Too_Small: region request is too large for buffer

6	DMA_Buffer_In_Use: buffer already in use

Uses

EAX, EBX, ESI, Flags


VDMAD_Reserve_Buffer_Space
include vdmad.inc

VxDcall VDMAD_Reserve_Buffer_Space

The VDMAD_Reserve_Buffer_Space service allows other devices that are going to handle DMA to make sure that VDMAD allocates a buffer large enough for any transfers that they might require. It also allows a device to specify a maximum physical address that would be valid for the device's DMA requests (such as 1Mb for an XT.)  During the Init_Complete phase of initialization, VDMAD allocates the DMA buffer using all of the constraints specified by other devices. For example, the buffer is at least as big as the largest size specified by the calls to this service, and it allocates below the lowest maximum physical addresses specified.

This service is only available before the Init_Complete message.

Parameter	Description

EAX	Specifies the number of pages requested.

ECX	Specifies the maximum physical address that can be included in a DMA transfer. If this parameter is zero, there is no limit.

Returns

This service has no return value.

Uses

Flags


VDMAD_Scatter_Lock
include vdmad.inc

VxDcall VDMAD_Scatter_Lock

The VDMAD_Scatter_Lock service attempts to lock all pages mapped to a DMA region and return the actual physical addresses of the pages.

Parameter	Description

EBX	Specifies the virtual machine handle.

AL	Specifies the operation flags. The parameter can be one of the following values:

Value	Meaning

0	Fills the DDS table with physical addresses and sizes of the physical regions that make up the DMA region.

1	Fills the DDS table with the actual page table entries.

2	Prevents not-present pages from being locked. This value is ignored if bit 0 is not set.

EDI	Points to the extended DDS (DMA Descriptor Structure) to receive the information.

Returns

The carry flag is clear and the zero flag is set if the entire region is locked. The zero flag is clear if only a portion of the region is locked. If the carry flag is set, nothing is locked.

The EDX register contains the number of table entries needed to describe whole region, and the DDS_size field specifies the number of bytes locked.

If the request was for page table copy (AL set to 1 or 3), then The ESI register contains an offset into first page for start of the region.

Uses

EDX, ESI, Flags


VDMAD_Scatter_Unlock
include vdmad.inc

VxDcall VDMAD_Scatter_Unlock

The VDMAD_Scatter_Unlock service attempts to unlock all pages locked by a previous call to the VDMAD_Scatter_Lock service.

Parameter	Description

EBX	Specifies the virtual machine handle.

AL	Specifies the operation flags. The parameter can be one of the following values:

Value	Meaning

0	Fills the DDS table with physical addresses and sizes of the physical regions that make up the DMA region.

1	Fills the DDS table with the actual page table entries.

2	Prevents not-present pages from being locked. This value is ignored if bit 0 is not set.

4	Prevents pages from being marked as dirty. If bits 0 and 1 are set but 2 is clear, then not-present pages are not marked.

EDI	Points to the extended DDS (DMA Descriptor Structure) to receive the information.

Returns

The carry flag is clear if the lock counts have been decremented. If no other virtual devices had pages locked, the pages have been unlocked. The carry flag is set if the memory was not locked.

Comments

If Bits 0 and 1 in the AL register are set, the table at the end of the DDS is not required to unlock the previously locked pages; otherwise the table is not used and caller need not maintain the table after the lock call.

Uses

Flags


VDMAD_Set_EISA_Adr_Mode
include vdmad.inc

VxDcall VDMAD_Set_EISA_Adr_Mode

The VDMAD_Set_EISA_Adr_Mode service sets the EISA extended mode.

Parameter	Description

EAX	Specifies the channel number. It must be in the range 0 to 7.

EBX	Specifies the DMA handle.

CL	Specifies one of the following mode values:

Value	Meaning

0	8-bit I/O, with count in bytes

1	16-bit I/O, with count in words and adr shifted

2	32-bit I/O, with count in bytes

3	16-bit I/O, with count in bytes

Returns

This service has no return value.

Uses

Flags


VDMAD_Set_Phys_State
include vdmad.inc

VxDcall VDMAD_Set_Phys_State

The VDMAD_Set_Phys_State service programs the DMA controller state for a channel. The service takes the location and size of the buffer from the information passed in a previous call to the VDMAD_Set_Region_Info service.

Parameter	Description

EAX	Specifies the DMA handle.

EBX	Specifies the virtual machine handle.

DL	Specifies the mode.

DH	Specifies the extended mode.

Returns

This service has no return value.

Uses

Flags

See Also

VDMAD_Set_Region_Info


VDMAD_Set_Region_Info
include vdmad.inc

VxDcall VDMAD_Set_Region_Info

The VDMAD_Set_Region_Info service sets information about the current region assigned to a DMA handle. This service must be called before calling the VDMAD_Set_Phys_State service.

Parameter	Description

EAX	Specifies the DMA handle.

BL	Specifies the buffer identifier.

BH	Specifies whether pages are locked (zero if not locked, nonzero if locked).

ESI	Specifies the region linear.

ECX	Specifies the size in bytes.

EDX	Specifies the physical address for the transfer.

Returns

This service has no return value.

Uses

Flags


VDMAD_Set_Virt_State
include vdmad.inc

VxDcall VDMAD_Set_Virt_State

The VDMAD_Set_Virt_State service modifies the virtual state of a DMA channel. This service is used when a channel owner wants to change the virtual state of a channel from how the virtual machine programmed it. This might be used to split a DMA request into smaller pieces.

Parameter	Description

EAX	Specifies the DMA handle.

EBX	Specifies the virtual machine handle

ESI	Specifies either a high linear address or a physical byte address. If translation is enabled, this parameter is the high linear address of the user's DMA region. A high linear address is used so that the DMA can proceed even if a different virtual machine is actually running at the time of the transfer. If translation is not enabled, this parameter specifies a physical byte address programmed (shifted left 1, for word ports).

ECX	Specifies the count in bytes.

DL	Specifies the mode. This is the same as the 8237 mode byte with channel number removed and the following DMA_masked and DMA_requested values set as appropriate:

Value	Meaning

DMA_masked	Channel masked and not ready for a transfer

DMA_requested	Software request flag set

DH	Specifies the extended mode (ignored on non-PS2 machines that do not have extended DMA capabilities).

Returns

This service has no return value.

Uses

Flags


VDMAD_Unlock_DMA_Region
include vdmad.inc

VxDcall VDMAD_Unlock_DMA_Region

The VDMAD_Unlock_DMA_Region service unlocks the DMA region previously locked to a channel. It is called after a DMA transfer is complete and the channel has been masked,preventing the controller from attempting any further transfers to the programmed address.

Parameter	Description

ESI	Specifies the linear address of the actual DMA region.

ECX	Specifies the number of bytes in the DMA region.

Returns

The carry flag is clear if the memory is unlocked. Otherwise, the carry flag is set to indicate an error.

Uses

Flags


VDMAD_UnMask_Channel
include vdmad.inc

VxDcall VDMAD_UnMask_Channel

The VDMAD_UnMask_Channel service physically unmasks a channel so that DMA transfers can proceed.

Parameter	Description

EAX	Specifies the DMA handle.

EBX	Specifies the virtual machine handle.

Returns

This service has no return value.

Uses

Flags


VDMAD_Virtualize_Channel
include vdmad.inc

VxDcall VDMAD_Virtualize_Channel

The VDMAD_Virtualize_Channel service allows another virtual device to claim ownership of a standard DMA channel. The new owner registers a callback procedure that is called whenever the virtual state of the channel is changed as a result of I/O done in a virtual machine.

Parameter	Description

EAX	Specifies the channel number.

ESI	Specifies the callback procedure. If this parameter is zero, no callback procedure is called. See the Comments section for more information about the procedure.

Returns

The carry flag is clear and the EAX register contains the DMA handle if the service is successful. Otherwise, the carry flag is set if channel is already owned.

Uses

EAX, EDX, Flags

Comments

The system calls the callback procedure by passing it the following input parameters:

EAX     ; DMA handle

EBX     ; virtual machine handle

The procedure can modify EAX, EBX, ECX, EDX, ESI, EDI, and Flags.

In some cases a virtual device does not allow a virtual machine to perform DMA to a channel. Instead, the virtual device handles programming based on a private API and not on virtualized hardware I/O. This means it is possible to pass a zero to specify no callback procedure. VDMAD continues to trap the I/O for the channel, but never changes the physical state of the channel as a result of any virtual machine I/O.


Virtual MS-DOS Manager

DOSMGR_Add_Device	Adds a device to the device list

DOSMGR_BackFill_Allowed	Specifies whether backfilling is allowed

DOSMGR_Copy_VM_Drive_State	Copies the drive state

DOSMGR_Enable_Indos_Polling	Enables polling of Indos variable

_DOSMGR_Exec_VM	Schedules execution of a virtual machine

DOSMGR_Get_DOS_Crit_Status	Specifies whether MS-DOS is in critical section

DOSMGR_Get_IndosPtr	Returns address of Indos variable

DOSMGR_Get_Version	Returns version number

DOSMGR_Instance_Device	Instances a device driver

DOSMGR_LocalGlobalReg	Identifies local and global memory

DOSMGR_Remove_Device	Removes device from device list

_DOSMGR_Set_Exec_VM_Data	Sets the execution data


DOSMGR_Add_Device
include dosmgr.inc

VxDcall DOSMGR_Add_Device

The DOSMGR_Add_Device service adds a device to the device list.

Parameter	Description

EBX	Specifies the handle of the virtual machine to add device to. If this parameter is zero, the device is added to all virtual machines.

EAX	Specifies the address of device header. This address must be in low memory (less than 100000h).

Returns

The carry flag is clear if the service is successful. Otherwise, the carry flag is set if the device could not be added to device list.

Comments

The address of this device for the chain is computed as: (eax  4) & 0FFFFh : (eax & 000Fh)

This service links the device into the list but does not call it. If the device needs to be initialized, the caller must do it. This service adds the device to the end of the device chain. Therefore, this service cannot be used to replace an existing device. This service applies to character devices only. Block devices cannot be added with this service.

All devices put on the list this way are removed when Windows exits, including any devices added by virtual mode code.

The only supported method to add a device globally is to use the _Allocate_Global_V86_Data_Area service to allocate memory to contain the device header, initialize it, then call this routine to add it to the list. Global devices must be added during the Device_Init message. They cannot be added later. Local devices must be added at the VM_Init, VM_Critical_Init or Sys_VM_Init message or they will be global because they will be part of the initial VM state.

If this device hooks an interrupt and it is a local device, the vector must be set in the appropriate virtual machine during the VM_Init, VM_Critical_Init or Sys_VM_Init message.

A global device can also work this way, hooking the vector in every virtual machine. This allows the global device to be removed before Windows exits. The other method for a global device is to hook the vector during the Device_Init message which makes the hook part of the initial virtual machine state. Such a hook must be removed during the Sys_Critical_Exit message or the vector will point to a nonexistent device after Windows exits.

Uses

Flags


DOSMGR_BackFill_Allowed
include dosmgr.inc

VxDcall DOSMGR_BackFill_Allowed

The DOSMGR_BackFill_Allowed service specifies whether the MS-DOS configuration allows for low-memory backfills.

The V86MMGR device calls this service.

This service has no parameters.

Returns

The carry flag is clear if backfilling is allowed. Otherwise, the carry flag is set.

Comments

This service depends on the high MS-DOS state. Certain high MS-DOS configurations prevent low memory 640k backfill from being possible.

Uses

Flags


DOSMGR_Copy_VM_Drive_State
include dosmgr.inc

VxDcall DOSMGR_Copy_VM_Drive_State

The DOSMGR_Copy_VM_Drive_State service copies the drive and current directory state of all drives from one virtual machine into another virtual machine.

This service can be called during a Create_VM message since it does not simulate calls or interrupts in either virtual machine; it just copies instance data from one to the other.

Parameter	Description

EBX	Specifies the handle of the virtual machine to receive a copy of the drive state.

ESI	Specifies handle of the virtual machine from which to copy the drive state.

Returns

This service has no return value.

Comments

This service does not change the current drive of the destination virtual machine.

This service does not disturb the InitDrvDir value set using the _DOSMGR_Set_Exec_VM_Data service if it is called before the _DOSMGR_Exec_VM service. The processing of InitDrvDir occurs during calls to the _DOSMGR_Exec_VM service.

Uses

Flags


DOSMGR_Enable_Indos_Polling
include dosmgr.inc

VxDcall DOSMGR_Enable_Indos_Polling

The DOSMGR_Enable_Indos_Polling service enables the INDOS polling for the the Windows session. This allows TSR drivers that hook Interrupt 21h and claim the critical section by setting the internal MS-DOS INDOS flag to continue to operate normally.

This service is intended for use by the virtual DOSNET device so that it can enable polling if the installed network requires it. The virtual device must not call this service during a Sys_Critical_Init message.

This service has no parameters.

Returns

The carry flag is clear if INDOS polling is enabled. Otherwise, the carry flag is set to indicate polling was already enabled.

Comments

Enabling INDOS polling has a severe impact on overall system performance.

This service overrides the INDOSPOLLING value specified in the SYSTEM.INI file. Since the virtual MS-DOS manager evaluates the SYSTEM.INI file during the Init_Complete message, a virtual device must call this service during the Device_Init message.

Uses

Flags


_DOSMGR_Exec_VM
include dosmgr.inc

VxDcall _DOSMGR_Exec_VM <VM, V86Size, CallBack, RefData>

The _DOSMGR_Exec_VM service schedules the execution specified by previous call to the _DOSMGR_Set_Exec_VM_Data service and sets other parameters of the execution.

Parameter	Description

VM	Specifies the handle of the current virtual machine.

V86Size	Specifies the size in pages of the virtual machine. This is equal to the number of pages mapped using the MapIntoVM service starting at the first page in the virtual machine. This service does not map these pages; the value is simply used to set the MS-DOS size of the virtual machine.

CallBk	Specifies the callback procedure to call when the virtual machine terminates. If this parameter is zero, no callback is called.

RefData	Specifies reference data to pass to the callback procedure.

Returns

This service has no return value.

Comments

The system calls the callback when the virtual machine terminates. The callback receives the following input parameters:

EBP     ; points to a Client_Reg_Struc

EBX     ; virtual machine handle

EDX     ; points to reference data

The callback must preserve the EBX, EBP and segment registers. After the callback returns, the system carries out the normal virtual machine termination sequence. At this time the virtual machine is still in a running state. The callback can delay termination by delaying its return. However, the callback must simulate interrupts into the virtual machine to keep the scheduler moving if it is holding termination.


DOSMGR_Get_DOS_Crit_Status
include dosmgr.inc

VxDcall DOSMGR_Get_DOS_Crit_Status

The DOSMGR_Get_DOS_Crit_Status service specifies whether it is possible to call MS-DOS at the current time (that is, whether MS-DOS is in a critical section).

This service is intended for use by the virtual pageswap device to determine whether MS-DOS is currently available to page. This is an asynchronous service.

This service has no parameters.

Returns

The zero flag is set if MS-DOS can be called. Otherwise, the zero flag is clear if MS-DOS is in a critical section and must not be called.

Uses

Flags

Comments

This service does not specify whether Windows is in a critical section nor does it specify which virtual machine has ownership of MS-DOS.


DOSMGR_Get_IndosPtr
include dosmgr.inc

VxDcall DOSMGR_Get_IndosPtr

The DOSMGR_Get_IndosPtr service returns the linear address of the MS-DOS Indos and Errormode variables.

This service has no parameters.

Returns

The EAX register contains the linear address (V86 mode address) of Indos and Errormode word. The low byte is the Errormode variable, the high byte is Indos.

Comments

This is a low linear address. To examine the value in a virtual machine which is not the current virtual machine, the virtual device must add the virtual-machine high-linear address to this value.

Uses

EAX, Flags


DOSMGR_Get_Version
include dosmgr.inc

VxDcall DOSMGR_Get_Version

The DOSMGR_Get_Version service returns the virtual MS-DOS manager version number.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

Uses

EAX, Flags


DOSMGR_Instance_Device
include dosmgr.inc

VxDcall DOSMGR_Instance_Device

The DOSMGR_Instance_Device service instances the indicated installed MS-DOS character device driver.

This service is only valid during the Init_Complete message.

Parameter	Description

ESI	Points to the 8-character device name. This name must exactly match the name as it found in the device header in low memory. Characters must be in uppercase; case conversion is not performed. Names shorter than 8 characters must be padded with spaces. The colon (:) must not be used.

Returns

The carry flag is clear if the device is instanced. Otherwise, the carry flag is set to indicate one of the following errors:

No device with this name in device list

Device is in MS-DOS RAM BIOS (Segment of device == 70h)

User overides with the GLOBAL setting in SYSTEM.INI

Comments

This service applies only to installed character devices (device segment not equal to 70h). It cannot instance devices that are in the MS-DOS RAM BIOS because there is no way to determine their start and end addresses. It is the job of the MS-DOS instancing to correctly instance things related to character devices in the MS-DOS RAM BIOS.

This service instances the entire device. It cannot differentiate code and data.

This service is available during the Init_Complete message only and cannot work until the DOSMGR_Device_Init service is complete. The service is in the ICODE segment so it becomes invalid after the Init_Complete message. Calls to the _AddInstanceItem service are also invalid after Init_Complete.

Do not use this service to instance devices added with the DOSMGR_Add_Device service. To instance an added device, a virtual device must call the _AddInstanceItem service or use the GVDAInstance flag in the _Allocate_Global_V86_Data_Area service.

Uses

Flags


DOSMGR_LocalGlobalReg
include dosmgr.inc

VxDcall DOSMGR_LocalGlobalReg

The DOSMGR_LocalGlobalReg service specifies whether the indicated V86 memory region is local or global memory The VMM memory manager calls this service whenever the TestGlobalV86Mem service is called.

This service is only available for Windows 3.1 and later.

Parameter	Description

EDX	Specifies the page number of the start of the region.

EDI	Specifies the page number of the end of the region.

Returns

EAX

Value	Meaning

0	Page range is local

1	Page range is global

2	Page range is partially global and partially local

3	Page range is unknown

Comments

This service returns 3 unless the region is in a local high MS-DOS region.

This service supports high MS-DOS configurations for MS-DOS version 5.00 or later. Other load high configurations are supported only if the corresponding software hooks this service or the TestGlobalV86Mem service.

This service is page (4k) granular and not byte granular.

Uses

EAX, Flags


DOSMGR_Remove_Device
include dosmgr.inc

VxDcall DOSMGR_Remove_Device

The DOSMGR_Remove_Device service removes a device from the device list. The device must have been previously added using the DOSMGR_Add_Device service

Parameter	Description

EBX	Specifies the handle of the virtual machine from which to remove the device. If this parameter is zero, the device is removed from all virtual machines.

EAX	Specifies the address of device header. This parameter must be a low memory linear address (less than 100000h).

Returns

The carry flag is clear if the service is successful. Otherwise, the carry flag is set if the device could not be removed from device list.

Comments

Global calls to DOSMGR_Add_Device should not be mixed with local calls to DOSMGR_Remove_Device for the same device. All DOSMGR_Add_Device devices are automatically removed when Windows terminates.

This service removes the link to the device from the device list. It does not free any memory or resources that the device may have created or allocated.

Uses

Flags


_DOSMGR_Set_Exec_VM_Data
include dosmgr.inc

VxDcall _DOSMGR_Set_Exec_VM_Data, <VM, CommTail, PRGName, InitDrvDir>

The _DOSMGR_Set_Exec_VM_Data service sets the data for the initial execution into a virtual machine. It is reserved for exclusive use by the virtual shell device.

This service can be called during the Create_VM message since it does not simulate calls or interrupts into the virtual machine; it just sets instance data.

Parameter	Description

VM	Specifies the handle of the virtual machine_Handle to set execution data for.

CommTail	Points to the command tail for the execution. The tail can be up to 128 byte. The first byte must specify the number of bytes in the tail; the last byte must be 0Dh.

PRGName	Points to null-terminated string specifying the name of the program to execute.

InitDrvDir	Points to a null-terminated string specifying the initial directory and drive for the virtual machine. The drive letter must be a capital letter. The string must be less than or equal to 64 chars including null terminator.

If this parameter is zero, the service does not set the default directory. This form of the service is made by the DOSMGR_Exec_VM service. Other virtual devices should not use this form.

Returns

This service has no return value.

Comments

This service must be called before calling the _DOSMGR_Exec_VM service.

See Also

_DOSMGR_Exec_VM


Virtual MS-DOS Network Device

DOSNET_Do_PSP_Adjust	Indicates whether PSP adjustment is required

DOSNET_Get_Version	Returns version number

DOSNET_Send_FILESYSCHANGE	Specifies local drives


DOSNET_Do_PSP_Adjust
include dosnet.inc

VxDcall DOSNET_Do_PSP_Adjust

The DOSNET_Do_PSP_Adjust service specifies whether the virtual device requires unique PSP addresses for each virtual machine. The virtual MS-DOS manager calls this service to determine whether it should adjust PSP addresses for the virtual machines.

This service has no parameters.

Returns

The carry flag is clear if the virtual MS-DOS manager should adjust the PSP. Otherwise, the carry flag is set to prevent the virtual MS-DOS manager from adjusting the PSP.

The EAX register contains zero if the virtual MS-DOS manager should check the SYSTEM.INI file to determine whether to override the action specified by the carry flag. Otherwise, the EAX register contains nonzero to prevent the virtual device from checking the file.

Comments

A network that uses the MS-DOS PSP addresses as part of an ID should clear the carry flag and return to direct the virtual MS-DOS manager to adjust PSP addresses. The manager adjusts PSP addresses by starting each virtual machine at a different paragraph address (using the virtual machine identifier as the basis of the adjustment). Even so this technique does not guaranteed unique PSP addresses. To ensure uniqueness, network software should always use Get Current Virtual Machine ID (Interrupt 2Fh, Function 1683h) to retrieve the virtual machine identifier and use this identifier to create an unique network ID.

Uses

EAX, Flags


DOSNET_Get_Version
include dosnet.inc

VxDcall DOSNET_Get_Version

The DOSNET_Get_Version service returns the virtual DOSNET device version number.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

The carry flag is clear.

Uses

EAX, Flags


DOSNET_Send_FILESYSCHANGE
include dosnet.inc

VxDcall DOSNET_Send_FILESYSCHANGE

The DOSNET_Send_FILESYSCHANGE service specifies whether the given drive is local to the virtual machine. If the drive is local, the WM_FILESYSCHANGE message can be broadcast to Windows applications when changes to the drive are made by MS-DOS applications.

Parameter	Description

AL	Specifies the drive number (0 = A, 1 = B, etc.)

EBX	Specifies the handle of the virtual machine to check.

Returns

The carry flag is clear if the WM_FILESYSCHANGE message will be sent for the specified drive. Otherwise, the carry flag is set to prevent messages for the drive.

Comments

This service is designed exclusively for the virtual DOSNET device. Other virtual devices should not provide their own implementations, however, they can hook this service. Since the virtual DOSNET device does not install if there is no redirector, a virtual device which hooks this service must ship with a modified DOSNET device which always loads.

A virtual device must not send a WM_FILESYSCHANGE message for a drive that this service has not acknowledged. Sending a message incorrectly can result in unexpected errors in Windows applications.

Uses

Flags


Virtual EBIOS Device

EBIOS_Get_Unused_Mem	Identifies unused EBIOS region

EBIOS_Get_Version	Returns version number


EBIOS_Get_Unused_Mem
include ebios.inc

VxDcall EBIOS_Get_Unused_Mem

The EBIOS_Get_Unused_Mem service returns information about any unused portion of the EBIOS region.

This service is intended for the use of the virtual MS-DOS manager.

This service has no parameters.

Returns

The carry flag is clear if the service is successful. The EAX register contains the segment address of start of unused EBIOS region, and the ECX register contains the size of the region in paragraphs. This size is zero if there is no unused EBIOS region. If the zero flag is set, the unused EBIOS region is global, that is, the region is in the same physical page in all virtual machines. Otherwise, the unused EBIOS region is local and is in different physical pages in each virtual machine.

The carry flag is set if the EBIOS device is not installed or all EBIOS memory is used by EBIOS.

Comments

On some machines, the size of the EBIOS region is not an even multiple of pages. Since the system requires that the EBIOS region be rounded to page boundaries, part of the EBIOS region may be unused.

If the EBIOS region is below the first V86 page, this service must set the carry flag and return.

Uses

EAX, ECX, Flags


EBIOS_Get_Version
include ebios.inc

VxDcall EBIOS_Get_Version

The EBIOS_Get_Version service returns the virtual EBIOS device version number and the location and size of the EBIOS pages.

Parameter	Description

This service has no parameters.

Returns

The carry flag is clear if the service is successful. The EAX register contains the version number, the EDX register contains number of the first page, and the ECX register contains the number of pages.

The carry flag is set if the virtual EBIOS device is not installed and EBIOS pages are not allocated.

Uses

EAX, ECX, EDX, Flags


Virtual Hard Disk Device

VHD_Allocate_Handle	Allocates a disk handle

VHD_Get_Version	Returns version number

VHD_Read	Reads from a drive

VHD_Write	Writes to a drive


VHD_Allocate_Handle
include vhd.inc

VxDcall VHD_Allocate_Handle

The VHD_Allocate_Handle service allocates a handle for an operation.

Parameter	Description

ESI	Specifies the address to call when the operation completes. If this parameter is zero, the address is not called.

Returns

If the carry flag is clear, the EAX register contains the disk handle. Otherwise, the carry flag is set if the service could not allocate the handle.

Uses

EAX, Flags


VHD_Get_Version
include vhd.inc

VxDcall VHD_Get_Version

The VHD_Get_Version service returns the VHD version number.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

The CL register contains the number of drives supported (0-based).

The EDX register can contain the following flag value:

Value	Meaning

1	Supports direct to hardware read and write operations.

The carry flag is clear.

Uses

EAX, Flags


VHD_Read
include vhd.inc

VxDcall VHD_Read

The VHD_Read service reads from the device.

Parameter	Description

EAX	Specifies a disk handle previously created using the VHD_Allocate_Handle service.

EBX	Specifies the starting sector.

CL	Specifies the sector count. If this parameter is zero, 256 sectors are read.

CH	Specifies the drive number.

ESI	Points to the buffer to receive the sector data. This buffer must be locked.

Returns

This service has no return value.


VHD_Write
include vhd.inc

VxDcall VHD_Write

The VHD_Write service writes to the device.

Parameter	Description

EAX	Specifies a disk handle previously created using the VHD_Allocate_Handle service.

EBX	Specifies the starting sector.

CL	Specifies the sector count. If this parameter is zero, 256 sectors are written.

CH	Specifies the drive number.

ESI	Points to the buffer containing the sector data. This buffer must be locked.

Returns

This service has no return value.


Virtual Interrupt 13 Device

Int13_Device_Registered	Registers an int 13h device

Int13_Hooking_BIOS_Int	Notifies when BIOS is hooked

Int13_Translate_VM_Int	Notifies when Int 13h is intercepted

Int13_Unhooking_BIOS_Int	Notifies when BIOS is unhooked


Int13_Device_Registered
include int13.inc

VxDcall Int13_Device_Registered

The Int13_Device_Registered service is called by the virtual block device whenever a block device driver identifies itself as an Interrupt 13h drive.

Parameter	Description

EDI	Points to a Block Device Descriptor.

Returns

The carry flag is clear if the service is successful. Otherwise, the carry flag is set to indicate an error such as unable to allocate a handle or specified Interrupt 13h drive is already registered.

Uses

Flags


Int13_Hooking_BIOS_Int
include int13.inc

VxDcall Int13_Hooking_BIOS_Int

The Int13_Hooking_BIOS_Int service notifies the virtual device that the BIOS Interrupt 13h interrupt has been hooked. The virtual block device calls this service.

Parameter	Description

EAX	Specifies the address (CS:IP) of the original Interrupt 13h BIOS handler.

ECX	Specifies the address (CS:IP) of the original ROM BIOS Interrupt 13h hook.

Returns

This service has no return value.

Comments

This service is always called at least once during initialization, but it must remain resident since it can also be called at system exit time.

The virtual block device calls this service after the interrupt has been hooked. If the service needs to call the BIOS, it should use the Build_Int_Stack_Frame and Resume_Exec services instead of the Exec_Int service.

This service should save the value in the ECX register to let the Int13_Translate_VM_Int service chain to the original ROM BIOS at any point in time. Since this virtual device always replaces the ROM BIOS, the EAX value can be ignored.

Uses

EAX, EBX, ECX, EDX, ESI, EDI, and Flags


Int13_Translate_VM_Int
include int13.inc

VxDcall Int13_Translate_VM_Int

The Int13_Translate_VM_Int service notifies the virtual device that an Int 13h has been intercepted. The virtual block device calls this service.

Parameter	Description

EBX	Specifies the handle of the current virtual machine.

EBP	Points to a Client_Reg_Struc structure containing the register values for the specified virtual machine.

Returns

This service has no return value.


Int13_Unhooking_BIOS_Int
include int13.inc

VxDcall Int13_Unhooking_BIOS_Int

The Int13_Unhooking_BIOS_Int service notifies the virtual device that the Int 13h BIOS is being unhooked. The virtual block device calls this service before the Interrupt 13h chain is actually unhooked.

Parameter	Description

EAX	Specifies the address (CS:IP) of the original MS-DOS BIOS Interrupt 13h hook.

ECX	Specifies the address (CS:IP) of the original ROM BIOS Interrupt 13h hook.

Returns

This service has no return value.

Uses

EAX, EBX, ECX, EDX, ESI, EDI, and Flags


Virtual Keyboard Device

VKD_API_Force_Key	Forces a key into a virtual machine

VKD_API_Get_Version	Returns version number

VKD_Cancel_Hot_Key_State	Cancels a hot key state

VKD_Cancel_Paste	Cancels a paste operation

VKD_Define_Hot_Key	Defines a hot key

VKD_Define_Paste_Mode	Sets the paste mode for the virtual machine

VKD_Flush_Msg_Key_Queue	Flushes message queue

VKD_Force_Keys	Forces scan codes into the keyboard buffer

VKD_Get_Kbd_Owner	Returns focus owner handle

VKD_Get_Msg_Key	Returns a key from the buffer

VKD_Get_Version	Returns version number

VKD_Local_Disable_Hot_Key	Disables a hot key

VKD_Local_Enable_Hot_Key	Enables a hot key

VKD_Peek_Msg_Key	Returns a key from the buffer

VKD_Reflect_Hot_Key	Reflects a hot key into a virtual machine

VKD_Remove_Hot_Key	Removes a defined hot key

VKD_Start_Paste	Starts the paste mode


VKD_API_Force_Key
include vkd.inc

VxDcall VKD_API_Force_Key

The VKD_API_Force_Key service forces a key into a virtual machine as if it was typed on the keyboard. VKD will scan these forced keys for hot keys, so forcing VKD hot keys is allowed.

Parameter	Description

EBX	Specifies the virtual machine handle or 0 for current focus.

CH	Specifies the scan code.

CL	Specifies the repeat count (1 or more).

EDX	Specifies the shift state (-1 means no change).

Returns

The carry flag is set if an error occurs.

Comments

This service is currently limited to the focus virtual machine, so the service fails if the EBX register is not zero or not the focus virtual machine handle.

Uses

Flags


VKD_API_Get_Version
include vkd.inc

VxDcall VKD_API_Get_Version

The VKD_API_Get_Version service returns the version number of the VKD.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

The carry flag is clear.

Uses

EAX, Flags


VKD_Cancel_Hot_Key_State
include vkd.inc

VxDcall VKD_Cancel_Hot_Key_State

The VKD_Cancel_Hot_Key_State service cancels the hot key state.

This service has no parameters.

Returns

This service has no return value.


VKD_Cancel_Paste
include vkd.inc

VxDcall VKD_Cancel_Paste

The VKD_Cancel_Paste service cancels the paste that was started in the virtual machine by the VKD_Start_Paste service.

Parameter	Description

EBX	Specifies the virtual machine handle.

Returns

This service has no return value.


VKD_Define_Hot_Key
include vkd.inc

VxDcall VKD_Define_Hot_Key

The VKD_Define_Hot_Key service defines a hot-key-notification callback procedure. Hot keys are detected by ANDing the shift state mask with the global shift state, then comparing the resulting state with the shift state compare value. If this matches and the key code matches, the callback procedure is called with the specified reference data in EDX.

Parameter	Description

AL	Specifies scan code of the main key.

AH	Specifies the type of scan code. This parameter can be one of the following values:

Value	Meaning

0	Normal code

1	Extended code (ExtendedKey_B)

0FFh	Either normal or extended (AllowExtended_B)

EBX	Specifies shift state. The high word is a mask that is ANDed with the global shift state when checking for this hot key. The low word is the masked-shift-state-compare value.

CL	Specifies the operation flags. This parameter can be one of the following values:

Value	Meaning

CallOnPress	Calls callback when key press is detected.

CallOnRelease	Calls callback when key release is detected. Keyboard may still be in hot-key hold state.

CallOnRepeat	Calls callback when repeated press is detected.

CallOnComplete	Calls callback when the hot key state is ended (all shift modifier keys are released) or when a different hot key is entered. For example, assume that both ALT+1 and ALT+2 are hot keys. If the user holds the ALT key down, then presses and releases the 1 key and presses the 2 key, the callback for ALT+1 is call even though the ALT key has not been released.

CallOnUpDwn	Calls on both press and release.

CallOnAll	Calls on press, release and repeats.

PriorityNotify	Specifies that the callback can only be called when interrupts are enabled and the critical section is not owned. This value can be combined with any other value in this list.

Local_Key	Specifies that the key can be locally enabled or disabled.

ESI	Points to the callback procedure.

EDX	Points to the reference data to pass to the callback procedure.

EDI	Specifies maximum notification delay in milliseconds if the CL register specifies the PriorityNotify value. If this parameter is zero, the callback is always notified.

Returns

If the carry flag is clear, the EAX register contains the definition handle. Otherwise, the carry flag is set to indicate an error.

Comments

The callback procedure is called when a hot key is detected, and detection meets mask requirements. The callback receives the following input parameters:

AL    ; scan code of key

AH    ; 0 if key just pressed (Hot_Key_Pressed)

      ; 1 if key just released (Hot_Key_Released)

      ; 2 if key is an auto-repeat press (Hot_Key_Repeated)

      ; 3 hot key state ended (Hot_Key_Completed)

EBX   ; hot key handle

ECX   ; global shift state

EDX   ; points to the reference data

EDI   ; elapsed time for delayed notification in milliseconds

The EDI register normally contains zero, but if the PriorityNotify value is specified this value could be larger.

The high bit of the AH register is set if the hot key is a priority hot key and the virtual machine which had the keyboard focus at the time the hot key was recognized was suspended or not executable. In this case, the priority event was scheduled for the system virtual machine rather than the keyboard owner. The Hot_Key_SysVM_Notify value can be used to check this bit.

The callback procedure can modify EAX, EBX, ECX, EDX, ESI, EDI, and Flags

Uses

Flags


VKD_Define_Paste_Mode
include vkd.inc

VxDcall VKD_Define_Paste_Mode

The VKD_Define_Paste_Mode service selects the virtual-machine paste mode and specifies whether Interrupt 16h pasting can be attempted or not. Some applications hook Interrupt 09h which often disallows pasting using Interrupt 16h. The VKD can detect this by setting a time-out to see if any Interrupt 16h handling is being done by the application. If not, the VKD switches to Interrupt 09h paste.

If an application does some Interrupt 16h handling, but cannot support the Interrupt 16h paste operation, a PIF bit can be set to indicate that only Interrupt 09h pasting should be used.

Parameter	Description

AL	Specifies whether to use Interrupt 16h or Interrupt 09h paste. It can be one of the following values:

Value	Meaning

0	Allows Interrupt 16h paste attempts

1	Forces Interrupt 09h pasting

EBX	Specifies the virtual machine handle.

Returns

This service has no return value.

Uses

Flags


VKD_Flush_Msg_Key_Queue
include vkd.inc

VxDcall VKD_Flush_Msg_Key_Queue

The VKD_Flush_Msg_Key_Queue service flushes any available keys from the special message mode input buffer.

Parameter	Description

EBX	Specifies the virtual machine handle.

Returns

This service has no return value.

Uses

Flags


VKD_Force_Keys
include vkd.inc

VxDcall VKD_Force_Keys

The VKD_Force_Keys service forces scan codes into the keyboard buffer just as if they had been typed on the physical keyboard. These keys are processed in the context of the focus virtual machine.

Parameter	Description

ESI	Points to a buffer of scan codes.

ECX	Specifies the number of scan codes in the buffer.

Returns

The carry flag is set if the keyboard buffer overflows. In this case, The ECX register contains the number of remaining scan codes that did not fit.

Uses

Flags


VKD_Get_Kbd_Owner
include vkd.inc

VxDcall VKD_Get_Kbd_Owner

The VKD_Get_Kbd_Owner service returns the virtual machine handle of the keyboard focus virtual machine.

This service has no parameters.

Returns

The EBX register contains the virtual machine handle of the keyboard owner.

Uses

Flags, EBX


VKD_Get_Msg_Key
include vkd.inc

VxDcall VKD_Get_Msg_Key

The VKD_Get_Msg_Key service returns the next available key from the special message mode input buffer and removes it from the buffer. If no key is available, then the zero flag is set.

This service does not block.

Parameter	Description

EBX	Specifies the virtual machine handle.

Returns

The zero flag is clear if a key is read. The AL register contains the scan code and the AH register contains a combination of the following modifier flag values:

Value	Meaning

MK_Shift	A shift key is down

MK_Ctrl	A control key is down

MK_Alt	An ALT key is down

MK_Extended	The key is an extended key

The zero flag is set if no key is available.

Uses

EAX, Flags


VKD_Get_Version
include vkd.inc

VxDcall VKD_Get_Version

The VKD_Get_Version service returns the VKD version number.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

Uses

EAX, Flags


VKD_Local_Disable_Hot_Key
include vkd.inc

VxDcall VKD_Local_Disable_Hot_Key

The VKD_Local_Disable_Hot_Key service disables a hot key in the specified virtual machine.

Parameter	Description

EAX	Specifies the hot key handle.

EBX	Specifies the virtual machine handle.

Returns

This service has no return value.

Uses

Flags


VKD_Local_Enable_Hot_Key
include vkd.inc

VxDcall VKD_Local_Enable_Hot_Key

The VKD_Local_Enable_Hot_Key service enables a hot key in the specified virtual machine.

Parameter	Description

EAX	Specifies the hot key handle.

EBX	Specifies the virtual machine handle.

Returns

This service has no return value.

Uses

Flags


VKD_Peek_Msg_Key
include vkd.inc

VxDcall VKD_Peek_Msg_Key

The VKD_Peek_Msg_Key service returns the next available key from the special message mode input buffer without removing it from the buffer. If no key is available, the zero flag is set.

Parameter	Description

EBX	Specifies virtual machine handle

Returns

The zero flag is clear if a key is read. The AL register contains the scan code and the AH register contains a combination of the following modifier flag values:

Value	Meaning

MK_Shift	A shift key is down

MK_Ctrl	A control key is down

MK_Alt	An ALT key is down

MK_Extended	The key is an extended key

The zero flag is set if no key is available.

Uses

EAX, Flags


VKD_Reflect_Hot_Key
include vkd.inc

VxDcall VKD_Reflect_Hot_Key

The VKD_Reflect_Hot_Key service reflects a hot key into a specified virtual machine and cancels the hot key state. This service is normally called by a hot-key-notification callback procedure. It allows the callback to send the hot key into a virtual machine and without processing it as a hot key. VKD simulates the required key strokes to get the virtual machine into the specified shift state, then it simulates the key strokes for the hot key itself, and finally simulates key strokes to get the virtual machine to match the current global shift state.

Parameter	Description

EAX	Specifies the hot key handle.

EBX	Specifies the virtual machine handle.

CX	Specifies the required shift state.

Returns

This service has no return value.

Uses

Flags


VKD_Remove_Hot_Key
include vkd.inc

VxDcall VKD_Remove_Hot_Key

The VKD_Remove_Hot_Key service removes a defined hot key.

Parameter	Description

EAX	Specifies the definition handle of the hot key to remove. This handle must have been previously created using the VKD_Define_Hot_Key service.

Returns

This service has no return value.

Uses

Flags


VKD_Start_Paste
include vkd.inc

VxDcall VKD_Start_Paste

The VKD_Start_Paste service puts a virtual machine into paste mode by simulating keyboard activity with keystrokes taken from the specified paste buffer. Depending on the mode set with the VKD_Define_Paste_Mode service (default is to try Interrupt 16h pasting), VKD waits for the virtual machine to poll the keyboard BIOS through its Interrupt 16h interface. If the virtual machine does keyboard input through the BIOS, then VKD simulates the keyboard input at this high level (plugging in ASCII codes.)  If the virtual machine fails to perform any Interrupt 16h within in a time-out period, or the mode has been set to avoid Interrupt 16h pasting, the VKD simulates the necessary hardware interrupts to perform the pasting. Hot keys are still processed while pasting is in progress.

Parameter	Description

EAX	Points to the paste buffer containing an array of key structures having the following form:

    OEM_ASCII_value     db  ?

    scan_code           db  ?

    shift_state         dw  ?

The shift_state field is 02h if a shift key is down and 04h is a ctrl key is down.

The scan_code is 0FFh and the shift_state 0FFFFh, if the VKD should convert the key to a ALT+numpad sequence. This information is identical to what is given by the Window's keyboard routine OEMKeyScan.

EBX	Specifies the virtual machine handle.

ECX	Specifies the number of paste entries in the paste buffer.

ESI	Points to callback procedure. This parameter can be 0. See the Comments section for more information about the procedure.

EDX	Points to reference data to pass to the callback procedure.

Returns

The carry flag is clear if the paste is started. Otherwise, the carry flag is set to indicate an error such as insufficient memory to copy the buffer.

Comments

The callback procedure is called when the paste is complete or canceled. The callback receives the following input parameters:

EAX     ; Completion flags

        ; Paste_Complete - paste completed successfully

        ; Paste_Aborted  - paste canceled by user

        ; Paste_VM_Term  - paste aborted because virtual machine terminated

EBX     ; handle of virtual machine receiving the paste

EDX     ; reference data

The procedure can modify EAX, EBX, ECX, EDX, ESI, EDI, and Flags.

Uses

Flags


Virtual Math Coprocessor Device

VMCPD_Get_Version	Returns version number

VMCPD_Get_Virt_State	Returns virtual state

VMCPD_Set_Virt_State	Set virtual state


VMCPD_Get_Version
include vmcpd.inc

VxDcall VMCPD_Get_Version

The VMCPD_Get_Version service returns the VMCPD version number.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

The ECX register contains one of the following flag values:

Value	Meaning

0	No coprocessor

2	80287

3	80387

Uses

EAX, ECX, Flags


VMCPD_Get_Virt_State
include vmcpd.inc

VxDcall VMCPD_Get_Virt_State

The VMCPD_Get_Virt_State service returns the virtual state of EM and MP bits for the given virtual machine.

Parameter	Description

EBX	Specifies the virtual machine handle.

Returns

The AL register contains the virtual state of EM and MP bits. Bit 0 specifies the MPv bit; bit 1 the EMv bit.

Uses

EAX, Flags


VMCPD_Set_Virt_State
include vmcpd.inc

VxDcall VMCPD_Set_Virt_State

The VMCPD_Set_Virt_State service sets the virtual state of EM and MP bits for the given virtual machine.

Parameter	Description

EBX	Specifies the virtual machine handle.

AL	Specifies the new virtual state of the EM and MP bits. Bit 0 sets the MPv bit; bit 1 the EMv bit.

Returns

This service has no return value.

Uses

Flags


Virtual Mouse Device

Int33_API	Specifies position and state of mouse

VMD_Get_Mouse_Owner	Returns mouse owner handle

VMD_Get_Version	Returns version number

VMD_Set_Mouse_Type	Sets mouse type


Int33_API
include vmd.inc

VxDcall Int33_API

The Int33_API service is called by VMDOSAPP to inform the special mouse driver the new state of mouse buttons and position for the application being shown in a window. If the special mouse driver is not installed, then this call returns with carry flag set. If the API is not provided, then also it returns with carry flag set.

Parameter	Description

EAX	Specifies the Client_AX register. The high word is always zero.

Value	Meaning

1	Mouse API

Register	Description

Client_EBX	Specifies Handle of virtual machine on whose behalf the call is made

Client_EDI	Specifies (X,Y) position of mouse in pixels

Client_ECX	Specifies (event flags,state) where state is the button state of the mouse and event flags convey the change in button state from previous call.

2	Special mouse API presence test.

EBX	Specifies the handle of virtual machine making call

Returns

The carry flag is clear if the API is supported. Otherwise, carry flag is set to indicate the mouse driver is not special.

Uses

Flags


VMD_Get_Mouse_Owner
include vmd.inc

VxDcall VMD_Get_Mouse_Owner

The VMD_Get_Mouse_Owner service returns the handle of the virtual machine with the mouse focus.

This service has no parameters.

Returns

The EBX register contains the handle of virtual machine with mouse focus.

Uses

EBX, Flags


VMD_Get_Version
include vmd.inc

VxDcall VMD_Get_Version

The VMD_Get_Version service returns the version number.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

The carry flag is clear.

Uses

EAX, Flags


VMD_Set_Mouse_Type
include vmd.inc

VxDcall VMD_Set_Mouse_Type

The VMD_Set_Mouse_Type service sets the mouse type.

Parameter	Description

EAX	Specifies an IRQ number (if positive or zero) or an interrupt number (if negative). If this parameter is negative, the absolute value is the interrupt vector.

ECX	Specifies the mouse type. See VMD.INC for mouse definitions. If high bit of CL is set, then DL is equal to the COM port number (1-based).

Returns

The carry flag is clear if the mouse is virtualized. Otherwise, The EAX register contains one of the following error values:

Value	Meaning

00	Mouse already virtualized

01	Could not virtualize interrupt

Uses

EAX, Flags


Virtual PageSwap Device

PageSwap_Get_Version	Returns version number

PageSwap_Test_Create	Tests for available allocation space

PageSwap_Test_IO_Valid	Tests for valid I/O


PageSwap_Get_Version
include pageswap.inc

VxDcall PageSwap_Get_Version

The PageSwap_Get_Version service returns the virtual PageSwap device version number, the type of paging in effect, and the maximum size of the paging file in pages.

This service has no parameters.

Returns

The carry flag is clear if the virtual pageswap device is installed. The EAX register contains version number, the ECX register contains the maximum size of swap file in pages, and the BL register contains the pager type which is one of the following values:

Value	Meaning

1	No pager

2	MS-DOS pager

3	Direct hardware pager

The carry flag is set and the EAX register contains zero if the virtual device is not installed.

Comments

The maximum swap file size will not be valid until after the Device_Init message is processed.

Uses

Flags


PageSwap_Test_Create
include pageswap.inc

VxDcall PageSwap_Test_Create

The PageSwap_Test_Create service determines whether the virtual pageswap device can satisfy the specified allocation request. The VMM memory manager calls this service to check requests before allocating the memory.

The virtual pageswap device can satisfy the request if the request is less than or equal to the size of the swap file plus any physical memory not yet mapped to linear addresses.

Parameter	Description

ECX	Specifies the count of pages in the allocation request.

EAX	Specifies the allocation flags.

Returns

The carry flag is clear if the requested memory can be allocated.

Uses

Flags


PageSwap_Test_IO_Valid
include pageswap.inc

VxDcall PageSwap_Test_IO_Valid

The PageSwap_Test_IO_Valid service determines whether paging to and from disk can be performed. This service passes the call through to the virtual pagefile device.

This service has no parameters.

Returns

The carry flag is clear if paging is permitted. Otherwise, the carry flag is set to indicate that operations which may cause paging should be avoided.

Uses

Flags


Virtual PIC Device

VPICD_Call_When_Hw_Int	Installs callback for hardware interrupts

VPICD_Clear_Int_Request	Clears an interrupt request

VPICD_Convert_Handle_To_IRQ	Converts a handle to an IRQ number

VPICD_Convert_Int_To_IRQ	Converts a vector number to an IRG number

VPICD_Convert_IRQ_To_Int	Converts IRQ number to interrupt vector number

VPICD_Force_Default_Behavior	Unvirtualizes an IRQ

VPICD_Force_Default_Owner	Sets the owner for an IRQ number

VPICD_Get_Complete_Status	Returns complete IRQ status

VPICD_Get_IRQ_Complete_Status	Returns complete IRQ status

VPICD_Get_Status	Returns IRQ status

VPICD_Get_Version	Returns the version number and flags

VPICD_Phys_EOI	End physical interrupt

VPICD_Physically_Mask	Masks the physical IRQ

VPICD_Physically_Unmask	Unmasks the physical IRQ

VPICD_Set_Auto_Masking	Sets automatic masking

VPICD_Set_Int_Request	Sets an interrupt request

VPICD_Test_Phys_Request	Tests the state of the physical IRQ

VPICD_Virtualize_IRQ	Virtualizes an IRQ

VPICD_API_Get_Ver	Returns version number

VPICD_Install_Handler	Installs an interrupt handler

VPICD_Remove_Handler	Removes an interrupt handler

VID_Hw_Int_Proc	Handler for hardware interrupts

VID_Virt_Int_Proc	Handles virtual interrupts

VID_EOI_Proc	Handles end-of-interrupt

VID_Mask_Change_Proc	Handles changes to interrupt mask

VID_IRET_Proc	Handles interrupt returns

VPICD_IRQ_Descriptor	Virtualized IRQ Descriptor

Bimodal_Int_Struc	Information for bimodal interrupts

EBIS_Sel_Struc	Extra segment information


VPICD_Call_When_Hw_Int
include vpicd.inc

pushfd

cli                                 ; disable interrupts

mov     esi, OFFSET32 Callback      ; points to callback procedure

VxDcall VPICD_Call_When_Hw_Int

popfd

mov     [Next_Callback], esi        ; address of next callback in chain

The VPICD_Call_When_Hw_Int service installs a callback procedure for hardware interrupts. The system calls the callback procedure whenever a hardware interrupt occurs.

The caller must disable interrupts before calling this service.

Parameter	Description

Callback	Points to the callback procedure. When the system calls the procedure, the EBX register contains the handle of the current virtual machine.

Returns

The ESI register contains the address of the next procedure in the callback chain.

Comments

Although any virtual device can use this service, the service is intended for use by the virtual DMA device to detect completion of DMA transfers. On systems with hardware devices that interrupt frequently, use of this service should be avoided. Installing a callback procedure to process every hardware interrupt can have a major impact on performance.

The callback procedure is responsible for chaining to the next handler in the interrupt chain. It also must preserve the EBX register for the next handler.

Uses

ESI, Flags


VPICD_Clear_Int_Request
include vpicd.inc

mov     eax, IRQHand    ; IRQ handle

mov     ebx, VM         ; current VM handle

VxDcall VPICD_Clear_Int_Request

The VPICD_Clear_Int_Request service resets an IRQ request that was previously set by a call to the VPICD_Set_Int_Request service.

Parameter	Description

IRQHand	Specifies the handle of the IRQ to clear.

VM	Specifies the handle of the VM.

Returns

This service has no return value.

Comments

If the IRQ is being shared and another device has also set the virtual IRQ, this service does not reset the virtual request immediately. Instead, the request is reset only after the other device calls VPICD_Clear_Int_Request

Uses

Flags

See Also

VPICD_Set_Int_Request


VPICD_Convert_Handle_To_IRQ
include vpicd.inc

mov     eax, IRQHand        ; IRQ handle

VxDcall VPICD_Convert_Handle_To_IRQ

mov     [IRQNum], esi       ; IRQ number

The VPICD_Convert_Handle_To_IRQ service returns the number of the IRQ corresponding to the specified IRQ handle.

Parameter	Description

IRQHand	Specifies the handle of a virtualized IRQ.

Returns

The ESI register contains the IRQ number.

Uses

ESI, Flags

See Also

VPICD_Convert_Int_To_IRQ, VPICD_Convert_IRQ_To_Int


VPICD_Convert_Int_To_IRQ
include vpicd.inc

mov     eax, VecNum                 ; interrupt vector number

VxDcall VPICD_Convert_Int_To_IRQ

jc      not_mapped                  ; carry set if vector not mapped to IRQ

mov     [IRQNum], eax               ; IRQ number

The VPICD_Convert_Int_To_IRQ service returns the IRQ number (if any) corresponding to the specified interrupt vector number.

Parameter	Description

VecNum	Specifies an interrupt vector number.

Returns

The carry flag is clear and the EAX register contains the IRQ number if the interrupt vector number is mapped to an IRQ. Otherwise, the carry flag is set.

Comments

Since virtual machines can map IRQ numbers of the virtual PIC to any interrupt vector numbers, virtual devices should always explicitly check which interrupt vector is mapped to a particular IRQ.

Uses

EAX, Flags

See Also

VPICD_Convert_Handle_To_IRQ, VPICD_Convert_IRQ_To_Int


VPICD_Convert_IRQ_To_Int
include vpicd.inc

mov     eax, IRQNum     ; IRQ number (not an IRQ handle!)

mov     ebx, VM         ; VM handle

VxDcall VPICD_Convert_IRQ_To_Int

jc      not_valid       ; carry set if IRQ number is not valid

mov     [VecNum], eax   ; interrupt vector number

The VPICD_Convert_IRQ_To_Int service returns the interrupt vector number that corresponds to the specified IRQ number for the specified virtual machine.

Parameter	Description

IRQNum	Specifies an IRQ number.

VM	Specifies the handle identifying the virtual machine.

Returns

The carry flag is clear and the EAX register contains an interrupt vector number if the IRQ number is valid. Otherwise, the carry flag is set.

Comments

Since virtual machines can map IRQ numbers of the virtual PIC to any interrupt vector numbers, virtual devices should always explicitly check which interrupt vector is mapped to a particular IRQ.

Uses

EAX, Flags

See Also

VPICD_Convert_Handle_To_IRQ, VPICD_Convert_Int_To_IRQ


VPICD_Force_Default_Behavior
include vpicd.inc

mov     eax, IRQHand        ; IRQ handle

VxDcall VPICD_Force_Default_Behavior

The VPICD_Force_Default_Behavior service unvirtualizes an IRQ. This allows a virtual device to remove virtualization of an IRQ when it processes a System_Exit message.

Parameter	Description

IRQHand	Specifies the handle of the IRQ to unvirtualize.

Returns

This service has no return value.

Comments

This service invalidates the IRQ handle. After calling this service, a virtual device must not attempt to use the IRQ handle.

Uses

Flags

See Also

VPICD_Force_Default_Owner


VPICD_Force_Default_Owner
include vpicd.inc

mov     eax, IRQNum     ; IRQ number

mov     ebx, VM         ; owner VM handle or 0 for global ownership

VxDcall VPICD_Force_Default_Owner

jc      error           ; carry set if can't set owner

The VPICD_Force_Default_Owner service forces VPICD's default interrupt handler to direct a specified IRQ to a particular virtual machine, or to make the IRQ global so that any virtual machine can receive the interrupt.

Parameter	Description

IRQNum	Specifies the number of the IRQ for which ownership is set.

VM	Specifies the handle identifying the virtual machine to receive ownership. If this parameter is 0, the IRQ is given global ownership and any virtual machine can receive the interrupt.

Returns

The carry flag is clear if the service set the owner to the specified virtual machine. If the service could not set the owner, such as if the IRQ has been virtualized or the IRQ number is not valid, the carry flag is set.

Uses

Flags

See Also

VPICD_Force_Default_Behavior


VPICD_Get_Complete_Status
include vpicd.inc

mov     eax, IRQHand        ; IRQ handle

mov     ebx, VM             ; VM handle

VxDcall VPICD_Get_Complete_Status

mov     [Status], ecx       ; IRQ status

The VPICD_Get_Complete_Status service returns the complete status for a virtual IRQ in a specified virtual machine.

Parameter	Description

IRQHand	Specifies the handle identifying the IRQ for which to receive status.

VM	Specifies the handle identifying the virtual machine.

Returns

The ECX register contains a combination of the following status flag values:

Value	Meaning

VPICD_Stat_IRET_Pending	A virtual iret is pending.

VPICD_Stat_In_Service	The IRQ is virtually in service.

VPICD_Stat_Phys_Mask	The IRQ is physically masked.

VPICD_Stat_Phys_In_Serv	The IRQ is physically in service.

VPICD_Stat_Virt_Mask	The virtual machine has masked the IRQ.

VPICD_Stat_Virt_Req	The virtual interrupt request for the virtual machine has been set (by a virtual device, not necessarily the caller).

VPICD_Stat_Phys_Req	The physical interrupt request has been set.

VPICD_Stat_Virt_Dev_Req	The virtual interrupt request has been set by the calling virtual device.

Uses

ECX, Flags

See Also

VPICD_Get_Status


VPICD_Get_IRQ_Complete_Status
include vpicd.inc

mov     eax, IRQNum             ; IRQ number

VxDcall VPICD_Get_IRQ_Complete_Status

jc      already_virtualized     ; carry set if IRQ is already virtualized

mov     [Status], ecx           ; status

The VPICD_Get_IRQ_Complete_Status service returns the complete status for the specified IRQ. This service is similar to VPICD_Get_Complete_Status except that it takes an IRQ number as a parameter instead of an IRQ handle.

Parameter	Description

IRQNum	Specifies the number of the IRQ for which to retrieve status.

Returns

The carry flag is set if the IRQ has been virtualized. Otherwise, the carry flag is clear.

The ECX register contains a combination of the following status flag values:

Value	Meaning

VPICD_Stat_IRET_Pending	A virtual iret is pending.

VPICD_Stat_In_Service	The IRQ is virtually in service.

VPICD_Stat_Phys_Mask	The IRQ is physically masked.

VPICD_Stat_Phys_In_Serv	The IRQ is physically in service.

VPICD_Stat_Virt_Mask	The virtual machine has masked the IRQ.

VPICD_Stat_Virt_Req	The virtual interrupt request for the virtual machine has been set (by a virtual device, not necessarily the caller).

VPICD_Stat_Phys_Req	The physical interrupt request has been set.

VPICD_Stat_Virt_Dev_Req	The virtual interrupt request has been set by the calling virtual device.

Comments

Virtual devices typically use this service to inspect an IRQ before attempting to virtualize it, or to inspect the state of another virtual device's interrupt. Since the service indicates whether an IRQ has been virtualized, virtual devices use this service to avoid conflicts when more than one device may want to use an IRQ.

Uses

ECX, Flags

See Also

VPICD_Get_Complete_Status


VPICD_Get_Status
include vpicd.inc

mov     eax, IRQHand        ; IRQ handle

mov     ebx, VM             ; VM handle

VxDcall VPICD_Get_Status

mov     [Status], ecx       ; IRQ status

The VPICD_Get_Status service returns the status for a virtual IRQ in a specified virtual machine. Although this service does not return the complete status, it returns the most commonly used information and is much faster than the VPICD_Get_Complete_Status service.

Parameter	Description

IRQHand	Specifies the handle identifying the IRQ for which to receive status.

VM	Specifies the handle identifying the virtual machine.

Returns

The ECX register contains a combination of the following status flag values:

Value	Meaning

VPICD_Stat_IRET_Pending	A virtual iret is pending.

VPICD_Stat_In_Service	The IRQ is virtually in service.

Uses

ECX, Flags

See Also

VPICD_Get_Complete_Status


VPICD_Get_Version
include vpicd.inc

VxDcall VPICD_Get_Version

mov     byte ptr [Major], ah        ; major version number

mov     byte ptr [Minor], al        ; minor version number

mov     [Flags], ebx                ; configuration flags

mov     [MaxIRQ], ecx               ; maximum IRQ supported

The VPICD_Get_Version service returns the VPICD major and minor version numbers.

This service has no parameters.

Returns

The carry flag is always clear, and the following registers contain the specified values:

Register	Value

AH	Specifies the major version number for the virtual PIC device.

AL	Specifies the minor version number for the virtual PIC device.

EBX	Specifies the configuration flag for the PIC. The flag can be the following value:

Value	Meaning

1	System has a master/slave (PC/AT-type) configuration. If this value is not given, the system has a single PIC ( PC/XT-type) configuration.

All other values are reserved.

ECX	Specifies the maximum IRQ supported. It is either 07h or 0Fh.

Uses

EAX, EBX, ECX, Flags


VPICD_Phys_EOI
include vpicd.inc

mov     eax, IRQHand        ; IRQ handle

VxDcall VPICD_Phys_EOI

The VPICD_Phys_EOI service ends a physical interrupt, and allows further hardware interrupts from the specified IRQ.

Parameter	Description

IRQHand	Specifies the handle identifying the IRQ.

Returns

This service has no return value.

Comments

An interrupt that is physically in service will not suppress interrupts to lower priority IRQs since VPICD does not prioritize hardware interrupts. Therefore, it is acceptable for an interrupt to be physically in service for any arbitrary length of time.

Uses

Flags


VPICD_Physically_Mask
include vpicd.inc

mov     eax, IRQHand        ; IRQ handle

VxDcall VPICD_Physically_Mask

The VPICD_Physically_Mask service masks the specified IRQ on the hardware PIC. This suppresses all hardware interrupts on the IRQ until the VPICD_Physically_Unmask or VPICD_Set_Auto_Masking service is called.

Parameter	Description

IRQHand	Specifies the handle identifying the IRQ.

Returns

This service has no return value.

Uses

Flags

See Also

VPICD_Physically_Unmask, VPICD_Set_Auto_Masking


VPICD_Physically_Unmask
include vpicd.inc

mov     eax, IRQHand        ; IRQ handle

VxDcall VPICD_Physically_Unmask

The VPICD_Physically_Unmask service unmasks the specified IRQ on the hardware PIC.

Parameter	Description

IRQHand	Specifies the handle identifying the IRQ.

Returns

This service has no return value.

Comments

This service unmasks the physical IRQ without regard to mask state of the virtual machines. Even if every VM has masked the virtual IRQ, this service unmasks the physical IRQ.

Uses

Flags

See Also

VPICD_Physically_Mask, VPICD_Set_Auto_Masking


VPICD_Set_Auto_Masking
include vpicd.inc

mov     eax, IRQHand        ; IRQ handle

VxDcall VPICD_Set_Auto_Masking

The VPICD_Set_Auto_Masking enables automatic masking for the specified IRQ. When automatic masking is enabled, the system automatically masks the physical IRQ if all virtual machines have masked the corresponding virtual IRQs. However, if at least one virtual machine has the IRQ unmasked, the physical IRQ remains unmasked.

Parameter	Description

IRQHand	Specifies the handle identifying the IRQ.

Returns

This service has no return value.

Comments

Automatic masking is the default for every IRQ. It can be overridden by the VPICD_Physically_Mask and VPICD_Physically_Unmask services.

Uses

Flags

See Also

VPICD_Physically_Mask, VPICD_Physically_Unmask


VPICD_Set_Int_Request
include vpicd.inc

mov     eax, IRQHand    ; IRQ handle

mov     ebx, VM         ; current VM handle

VxDcall VPICD_Set_Int_Request

The VPICD_Set_Int_Request service sets a virtual interrupt request for the specified IRQ and virtual machine. Setting the request causes the system to simulate an interrupt. Although the simulation may occur immediately, in many cases it may not until a later point in time.

Parameter	Description

IRQHand	Specifies the handle identifying the IRQ to set.

VM	Specifies the handle identifying the virtual machine.

Returns

This service has no return value.

Comments

The interrupt is not simulated immediately if any of the following conditions are present:

The virtual machine has interrupts disabled

The virtual machine has masked the IRQ

A higher priority virtual IRQ is in service

The virtual machine is suspended, or not able to run

However, since the interrupt may be simulated immediately, a virtual device that has a virtual interrupt handler must be able to handle a call to the handler before this service returns.

Setting an interrupt request does not guarantee that the interrupt will be simulated. For example, if the VM has masked the interrupt and never unmasks it, the interrupt is never simulated. Also, a call to the VPICD_Clear_Int_Request service made before the virtual interrupt is simulated prevents the interrupt simulation.

The virtual VPIC device simulates a level-triggered PIC. This means that once a virtual EOI occurs, another interrupt will be simulated immediately unless the virtual interrupt request is cleared.

Uses

Flags

See Also

VPICD_Clear_Int_Request


VPICD_Test_Phys_Request
include vpicd.inc

mov     eax, IRQHand        ; IRQ handle

VxDcall VPICD_Test_Phys_Request

jc      irq_set             ; carry set if physical IRQ is set

The VPICD_Test_Phys_Request service returns with the carry flag set if the physical (hardware PIC) interrupt request is set for the specified IRQ.

Parameter	Description

IRQHand	Specifies the handle identifying the IRQ.

Returns

The carry flag is set if the physical interrupt request is set.

Uses

Flags

See Also

VPICD_Get_Complete_Status


VPICD_Virtualize_IRQ
include vpicd.inc

mov     edi, OFFSET32 vid       ; points to a VPICD_IRQ_Descriptor

VxDcall VPICD_Virtualize_IRQ

jc      error                   ; carry set if IRQ can't be virtualized

mov     [IRQHand], eax          ; IRQ handle

The VPICD_Virtualize_IRQ service assigns a virtual interrupt request to the calling virtual device.

This is not an asynchronous service.

Parameter	Description

vid	Points to a VPICD_IRQ_Descriptor structure containing information about the virtual IRQ. The VID_IRQ_Number and VID_Hw_Int_Proc fields in the VPICD_IRQ_Descriptor structure must be set before calling this service.

Returns

If the carry flag is clear, the EAX register contains the handle for the virtual IRQ. This handle is used for all subsequent communication with the virtual PIC device.

The carry flag is set to indicate an error such as the IRQ has already been virtualized or the IRQ number is not valid.

Comments

The IRQ can be shared by up to 32 virtual devices if every virtual device specifies the VPICD_Opt_Can_Share value in the VID_Options field of the VPICD_IRQ_Descriptor structure.

Uses

EAX, Flags

See Also

VPICD_Force_Default_Behavior


VPICD_API_Get_Ver
include bimodint.inc

mov     ax, VPICD_API_Get_Ver

call    [lpfnVPICD]             ; VPICD entry point address

jc      error                   ; carry set on error

mov     [Major], ah             ; major version number

mov     [Minor], al             ; minor version number

The VPICD_API_Get_Ver function returns the major and minor version numbers for the virtual PIC device.

Parameter	Description

lpfnVPICD	Specifies the entry point address of the API handler for the virtual PIC device.

Returns

The carry flag is clear and the AX register contains the major and minor version numbers, if the function is successful.


VPICD_Install_Handler
include bimodint.inc

les     di, bis             ; points to Bimodal_Int_Struc

mov     ax, VPICD_Install_Handler

call    [lpfnVPICD]

jc      error               ; carry set on error

The VPICD_Install_Handler function installs a bimodal interrupt handler for the IRQ specified by the BIS_IRQ_Number field in the Bimodal_Int_Struc structure.

Parameter	Description

bis	Points to a Bimodal_Int_Struc structure containing information about the interrupt handler to install.

lpfnVPICD	Specifies the entry point address of the API handler for the virtual PIC device.

Returns

If the carry flag is clear, the function is successful. Otherwise, the carry flag is set to indicate an error such as the IRQ has already been virtualized or the IRQ number is not valid.

Comments

This function virtualizes the specified IRQ and creates supervisor-mode selectors for the interrupt handler's code, data, and additional segments (if any). The function also sets the supervisor-mode API handler.

See Also

VPICD_Remove_Handler


VPICD_Remove_Handler
include bimodint.inc

les     di, bis             ; points to Bimodal_Int_Struc

mov     ax, VPICD_Remove_Handler

call    [lpfnVPICD]

jc      error               ; carry set on error

The VPICD_Remove_Handler function removes a bimodal interrupt handler for the IRQ specified by the BIS_IRQ_Number field in the Bimodal_Int_Struc structure.

Parameter	Description

bis	Points to a Bimodal_Int_Struc structure containing information about the interrupt handler to remove.

lpfnVPICD	Specifies the entry point address of the API handler for the virtual PIC device.

Returns

The carry flag is clear if the function is successful and set if an error occurs. The function returns an error if the IRQ has not been virtualized or the IRQ number is not valid.

Comments

This function unvirtualizes the specified IRQ and frees the supervisor-mode selectors for the interrupt handler's code, data, and additional segments (if any).

See Also

VPICD_Install_Handler


VID_Hw_Int_Proc
include vpicd.inc

mov     eax, IRQHand    ; IRQ handle

mov     ebx, VMId       ; current VM handle

call    VID_Hw_Int_Proc

jc      not_handled     ; carry set if interrupt not handled

The VID_Hw_Int_Proc procedure handles hardware interrupts for a virtual device. The system calls the procedure whenever a hardware interrupt occurs. Typically, VID_Hw_Int_Proc services the physical device, calls the VPICD_Phys_EOI service to end the physical interrupt, and sets the virtual IRQ request for a specific virtual machine.

The system disables interrupts before calling this procedure. The procedure can re-enable interrupts if necessary.

Parameter	Description

IRQHand	Specifies the handle identifying the interrupt request.

VMId	Specifies the handle identifying the current virtual machine.

Returns

The procedure clears the carry flag if it processed the interrupt. If the IRQ is sharable, the procedure can direct the system to pass the interrupt to the next handler by setting the carry flag. In this case, it must not process the interrupt.

Comments

The VMM services the procedure is allowed to call is limited. If processing the interrupt requires use of restricted services, this procedure should use the Schedule_Call_Global_Event service to schedule an event that performs the additional processing.

This procedure may modify EAX, EBX, ECX, EDX, ESI, and Flags.

This procedure must return using the ret instruction, not an iret instruction.

See Also

VPICD_IRQ_Descriptor


VID_Virt_Int_Proc
include vpicd.inc

mov     eax, IRQHand  ; IRQ handle

mov     ebx, VM       ; current VM handle

call    VID_Virt_Int_Proc

The VID_Virt_Int_Proc procedure handles virtual interrupts for a virtual device. The system calls the procedure whenever a simulated interrupt occurs. The procedure is useful for implementing critical sections around a simulated hardware interrupt.

The system disables interrupts before calling this procedure. The procedure can re-enable interrupts if necessary.

Parameter	Description

IRQHand	Specifies the handle identifying the interrupt request.

VM	Specifies the handle identifying the current virtual machine.

Returns

This procedure has no return value.

Comments

A virtual device requests a virtual interrupt by using the VPICD_Set_Int_Request service. Once set, the system simulates the interrupt at a convenient point in time. The call to this procedure signals that the simulated interrupt is underway and can no longer be canceled using the VPICD_Clear_Int_Request service.

A virtual device that uses this procedure usually also uses the VID_Virt_IRET_Proc procedure to detect the end of the simulated interrupt.

This procedure may modify EAX, EBX, ECX, EDX, ESI, and Flags.

See Also

VID_IRET_Proc, VPICD_IRQ_Descriptor


VID_EOI_Proc
include vpicd.inc

mov     eax, IRQHand  ; IRQ handle

mov     ebx, VM       ; current VM handle

call    VID_EOI_Proc

The VID_EOI_Proc procedure handles the end of an interrupt. The system calls this procedure whenever a hardware interrupt handler in the virtual machine issues an EOI. The procedure typically calls the VPICD_Clear_Int_Request and VPICD_Phys_EOI services to clear the virtual interrupt and end the physical interrupt.

The system disables interrupts before calling this procedure. The procedure can re-enable interrupts if necessary.

Parameter	Description

IRQHand	Specifies the handle for the interrupt request.

VM	Specifies the handle of the current virtual machine.

Returns

This procedure has no return value.

Comments

This procedure is typically used by a virtual device, such as the virtual mouse device, that lets a corresponding MS-DOS driver process hardware interrupts. The virtual device reflects the interrupt to the virtual machine that owns the mouse. The MS-DOS driver services the interrupt and issues issues an EOI. At this point, the system calls the VID_EOI_Proc procedure.

This procedure may modify EAX, EBX, ECX, EDX, ESI, and Flags.

See Also

VPICD_Clear_Int_Request, VPICD_Phys_EOI, VPICD_IRQ_Descriptor


VID_Mask_Change_Proc
include vpicd.inc

mov     eax, IRGHand    ; IRQ handle

mov     ebx, VMId       ; current VM handle

mov     ecx, Mask       ; zero if unmasking IRQ, nonzero if masking

call    VID_Mask_Change_Proc

The VID_Mask_Change_Proc procedure processes attempts to mask or unmask the specified IRQ. The system calls this procedure whenever a virtual machine attempts to mask or unmask an interrupt.

The system disables interrupts before calling this procedure. The procedure can re-enable interrupts if necessary.

Parameter	Description

IRQHand	Specifies the handle for the interrupt request.

VMId	Specifies the handle of the current virtual machine.

Mask	Specifies whether the IRQ is being masked or unmasked. This parameter is nonzero if the IRQ is being masked, and is zero if it is being masked.

Returns

This procedure has no return value.

Comments

A virtual device typically uses this procedure to detect contention for a device. The default interrupt routines use this callback to detect conflicts with nonglobal interrupts.

This procedure may modify EAX, EBX, ECX, EDX, ESI, and Flags.

See Also

VPICD_IRQ_Descriptor


VID_IRET_Proc
include vpicd.inc

clc

cmp     [TimeOut],0

jz      no_timeout

stc                         ; carry set if interrupt timed-out

no_timeout:

mov     eax, IRQHand        ; IRQ handle

mov     ebx, VM             ; current VM handle

call    VID_IRET_Proc

The VID_IRET_Proc procedure handles attempts by a virtual machine to return from an interrupt. The system calls this procedure whenever a virtual machine executes an iret instruction or whenever a time-out occurs for a simulated interrupt.

The system disables interrupts before calling this procedure. The procedure can re-enable interrupts if necessary.

Parameter	Description

IRQHand	Specifies the handle identifying the interrupt request.

VM	Specifies the handle identifying the current virtual machine.

Returns

This procedure has no return value.

Comments

This procedure is useful for devices that must simulate large numbers of interrupts in a short period of time. For example, the virtual COM device simulates an interrupt, allows one character to be read from the COM port, and waits for the virtual machine to execute an iret instruction before putting more data into the virtual COM receive buffer.

This procedure may modify EAX, EBX, ECX, EDX, ESI, and Flags.

See Also

VPICD_IRQ_Descriptor


VPICD_IRQ_Descriptor
VPICD_IRQ_Descriptor  STRUC

    VID_IRQ_Number       dw   ?

    VID_Options          dw   0

    VID_Hw_Int_Proc      dd   ?

    VID_Virt_Int_Proc    dd   0

    VID_EOI_Proc         dd   0

    VID_Mask_Change_Proc dd   0

    VID_IRET_Proc        dd   0

    VID_IRET_Time_Out    dd   500

VPICD_IRQ_Descriptor  ENDS

The VPICD_IRQ_Descriptor structure contains information about a virtualized IRQ.

Member	Description

VID_IRQ_Number	Specifies the number of the IRQ to virtualize.

VID_Options	Specifies the options for virtualizing the IRQ. It can be a combination of the following values:

Value	Meaning

VPICD_Opt_Read_Hw_IRR	Reads the hardware interrupt register.

VPICD_Opt_Can_Share	Virtual IRQ can be shared.

VID_Hw_Int_Proc	Points to the callback procedure that handles hardware interrupts for this IRQ.

VID_Virt_Int_Proc	Points to the callback procedure that handles virtual interrupts for this IRQ.

VID_EOI_Proc	Points to the callback procedure that handles end-of-interrupt commands for this IRQ.

VID_Mask_Change_Proc	Points to the callback procedure that handles changes to the IRQ mask for this IRQ.

VID_IRET_Proc	Points to the callback procedure that handles iret instructions for this IRQ.

VID_IRET_Time_Out	Specifies the maximum amount of time in milliseconds that the virtual PIC device allows before the time-out occurs.

Comments

Time-outs are very important to prevent 386 enhanced mode Windows from hanging while simulating a hardware interrupt.


Bimodal_Int_Struc
include bimodint.inc

Bimodal_Int_Struc       STRUC

BIS_IRQ_Number          dw      ?

BIS_VM_ID               dw      0

BIS_Next                dd      ?

BIS_Reserved1           dd      ?

BIS_Reserved2           dd      ?

BIS_Reserved3           dd      ?

BIS_Reserved4           dd      ?

BIS_Flags               dd      0

BIS_Mode                dw      0

BIS_Entry               dw      ?

BIS_Control_Proc        dw      ?

                        dw      ?

BIS_User_Mode_API       dd      ?

BIS_Super_Mode_API      dd      ?

BIS_User_Mode_CS        dw      ?

BIS_User_Mode_DS        dw      ?

BIS_Super_Mode_CS       dw      ?

BIS_Super_Mode_DS       dw      ?

BIS_Descriptor_Count    dw      ?

Bimodal_Int_Struc       ENDS

The Bimodal_Int_Struc structure contains information for a bimodal interrupt.

Member	Description

BIS_IRQ_Number	Specifies the IRQ number.

BIS_VM_ID	Specifies the handle identifying the virtual machine; this field is used by the virtual PIC device.

BIS_Next	Points to the next Bimodal_Int_Struc structure in this chain.

BIS_Reserved1	Reserved for IRQ handle; this field is used by the virtual PIC device.

BIS_Reserved2	Reserved for BIS address; this field is used by the virtual PIC device.

BIS_Reserved3	Reserved.

BIS_Reserved4	Reserved.

BIS_Flags	Specifies the bimodal interrupt flags. It must be 0.

BIS_Mode	Specifies user or supervisor mode. It is 0 for user mode; 4 for supervisor mode.

BIS_Entry	Specifies the offset to the interrupt service routine for this interrupt.

BIS_Control_Proc	Specifies the offset to the control procedure for this interrupt.

BIS_User_Mode_API	Points to the user-mode API procedure for this interrupt. The procedure must check for and carry out the following functions:

Function	Description

BIH_API_EOI	End interrupt.

BIH_API_Mask	Mask the physical IRQ.

BIH_API_Unmask	Unmask the physical IRQ.

BIH_API_Get_Mask	Retrieve the mask state of the physical IRQ.

BIH_API_Get_IRR	Retrieve the set state of the physical IRQ.

BIH_API_Get_ISR	Retrieve service state of the physical IRQ.

BIH_API_Call_Back	Calls specified callback procedure when given virtual machine runs.

BIS_Super_Mode_API	Points to the supervisor-mode API procedure for this interrupt; this field is set by the virtual PIC device.

BIS_User_Mode_CS	Specifies the selector for the user-mode code segment for the interrupt handler.

BIS_User_Mode_DS	Specifies the selector for the user-mode data segment for the interrupt handler.

BIS_Super_Mode_CS	Specifies the selector for the supervisor-mode code segment for the interrupt handler; this field is set by the virtual PIC device.

BIS_Super_Mode_DS	Specifies the selector for the supervisor-mode data segment for the interrupt handler; this field is set by the virtual PIC device.

BIS_Descriptor_Count	Specifies the number of additional EBIS_Sel_Struc structures immediately following this structure.

See Also

VPICD_Install_Handler, VPICD_Remove_Handler, EBIS_Sel_Struc


EBIS_Sel_Struc
include bimodint.inc

EBIS_Sel_Struc STRUC

EBIS_User_Mode_Sel  dw  ?

                    dw  ?

EBIS_Super_Mode_Sel dw  ?

EBIS_Sel_Struc ENDS

The EBIS_Sel_Struc structure contains user- and supervisor-mode selectors for extra segments used by a bimodal interrupt handler.

Member	Description

EBIS_User_Mode_Sel	Specifies an user-mode selector for an extra segment.

EBIS_Super_Mode_Sel	Specifies a supervisor-mode selector for an extra segment; this field is used by the virtual PIC device.

See Also

Bimodal_Int_Struc


Virtual Polling Device

VMPoll_Enable_Disable	Enables or disables polling

VMPoll_Get_Version	Returns version number

VMPoll_Reset_Detection	Resets idle detection


VMPoll_Enable_Disable
include vmpoll.inc

VxDcall VMPoll_Enable_Disable

The VMPoll_Enable_Disable service enables or disables polling of the specified virtual machine.

Parameter	Description

AL	Specifies whether to disable (zero) or enable (nonzero) polling.

EBX	Specifies the handle of the virtual machine to enable or disable polling for. If this parameter is zero, polling is globally enabled or disabled.

Returns

This service has no return value.


VMPoll_Get_Version
include vmpoll.inc

VxDcall VMPoll_Get_Version

The VMPoll_Get_Version service returns the VMPOLL version number.

Parameter	Description

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

Uses

EAX, Flags


VMPoll_Reset_Detection
include vmpoll.inc

VxDcall VMPoll_Reset_Detection

The VMPoll_Reset_Detection service disables the virtual device's idle detection for the specified virtual machine.

Other virtual devices call this service to temporarily disable polling. For example, the virtual COM device uses the service to prevent terminal programs from being detected as idle while they transfer files.

Parameter	Description

EBX	Specifies the handle of the virtual machine to disable idle detection for.

Returns

This service has no return value.

Uses

Flags


Virtual Shell Device

SHELL_Event	Posts a shell event

SHELL_Get_Version	Returns version number

SHELL_GetVMInfo	Returns PIF settings

SHELL_Message	Displays a message

SHELL_Resolve_Contention	Resolves device contention

SHELL_SYSMODAL_Message	Displays a system-modal message


SHELL_Event
include shell.inc

VxDcall SHELL_Event

The SHELL_Event service posts an event in the Windows shell to VMDOSAPP.

Parameter	Description

EBX	Specifies the virtual machine Handle for the event.

ECX	Specifies the event number.

AX	Specifies the wParam parameter for the event. The high 16 bits specify the special boost flags.

ESI	Points to the callback procedure for the event. If this parameter is zero, no callback procedure is called. See the Comments section for more information about this procedure.

EDX	Points to reference data for the event callback procedure.

Returns

The carry flag is clear if the event is placed in the queue. The EAX register contains the handle of the event but only if the ESI parameter is nonzero.

The carry flag is set to indicate an error such as the VMDOSAPP is not present or insufficient memory for placement.

Comments

The system calls the callback procedure with the following input parameters:

EDX     ; points to reference data

EBP     ; points to a VMDOSAPP Client_Reg_Struc frame

If the carry flag is clear on entry, the event was processed and the EBP register points to a Client_Reg_Struc structure containing the register values after the event returned. If the carry flag is set, the event could not be placed in the queue and only the EDX register contains valid data.

In both case, the EBX register does not contain a virtual machine handle.

Uses

EAX, Flags


SHELL_Get_Version
include shell.inc

VxDcall SHELL_Get_Version

The SHELL_Get_Version service returns the version number for the virtual shell device.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

The carry flag is clear.

Uses

EAX, Flags


SHELL_GetVMInfo
include shell.inc

VxDcall SHELL_GetVMInfo

The SHELL_GetVMInfo service allows a virtual device to retrieve PIF information settings for a virtual machine.

This service is only available for Windows 3.1 and later.

Parameter	Description

EBX	Specifies the handle of the virtual machine to examine.

Returns

The EAX register contains one or more of the following flag values for the specified virtual machine:

Value	Meaning

SGVMI_Windowed	Is Windowed

SGVMI_ALTTABdis	Alt+Tab is reserved

SGVMI_ALTESCdis	Alt+Esc is reserved

SGVMI_ALTSPACEdis	Alt+Space is reserved

SGVMI_ALTENTERdis	Alt+Enter is reserved

SGVMI_ALTPRTSCdis	Alt+PrtSc is reserved

SGVMI_PRTSCdis	PrtSc is reserved

SGVMI_CTRLESCdis	Ctrl+Esc is reserved

SGVMI_HasHotKey	Has a shortcut key

SGVMI_Polling	Polling detection Enabled

SGVMI_FastPaste	Allow Fast paste Enabled

SGVMI_NoHMA	No HMA

SGVMI_XMS_Lock	XMS Hands Locked

SGVMI_EMS_Lock	EMS Hands Locked

SGVMI_V86_Lock	V86 Memory Locked

SGVMI_ClsExit	Close on Exit Enabled

The ECX, EDX, ESI, and EDI register contents are reserved.

Comments

The undefined bits in the EAX register are reserved. Do not depend on them being zero.

This service is not valid until after all virtual devices have processed the Create_VM message. This service if called during a Create_VM message will not return proper PIF information.

Uses

EAX, ECX, EDX, ESI, EDI, Flags


SHELL_Message
include shell.inc

VxDcall SHELL_Message

The SHELL_Message service displays a message box using the Windows shell.

Parameter	Description

EBX	Specifies the handle of the virtual machine responsible for the message.

EAX	Specifies the message box flags. See the MB_ symbols in the SHELL.INC file.

ECX	Points to null-terminated string containing the message text.

EDI	Points to null-terminated string containing the caption text. If this prarameter is zero, the service uses the standard caption. If this parameter points to an empty string, the message box has no caption.

ESI	Points to the callback procedure to call with response when the message box returns. If this parameter is zero, no callback procedure is called.

EDX	Specifies reference data to pas to the callback procedure.

Returns

The carry flag is clear and the EAX register contains the handle for the event if the service is successful.

Otherwise, the carry flag is set to indicate an error such as insufficient memory to display the message.

Comments

The system calls the callback procedure after the message box is complete. The callback receives the following input parameters:

EAX     ; response code from the message box

EDX     ; points to reference data

The response code in the EAX register is one of the ID symbols defined in the SHELL.INC file.

The EBX register may or may not contain the current virtual machine handle when the callback is called. The callback must not rely on its value.

If this service returns an error, a virtual device can use the SHELL_Sysmodal_Message service to force the system to display a message.

Uses

EAX, Flags


SHELL_Resolve_Contention
include shell.inc

VxDcall SHELL_Resolve_Contention

The SHELL_Resolve_Contention service resolves contention for the MS-DOS shell.

Parameter	Description

EAX	Specifies the virtual machine handle of the current device owner.

EBX	Specifies the handle of the contending virtual machine. This parameter must identify the current virtual machine.

ESI	Points to an 8-byte string identifying the name of the device in contention. The name must be in uppercase letters and be padded with spaces if necessary.

Returns

The EBX register contains the virtual machine handle of contention winner. If the carry flag is set, contention could not be resolved.

Uses

EBX, Flags


SHELL_SYSMODAL_Message
include shell.inc

VxDcall SHELL_SYSMODAL_Message

The SHELL_SYSMODAL_Message service displays system model message box in the Windows shell.

Parameter	Description

EBX	Specifies the handle of the virtual machine responsible for the message.

EAX	Specifies the message box flags. See the MB_ symbols in the SHELL.INC file. The MB_SYSTEMMODAL value must be given.

ECX	Points to null-terminated string containing the message text.

EDI	Points to null-terminated string containing the caption text. If this parameter is zero, the service uses the standard caption. If this parameter points to an empty string, the message box has no caption.

Returns

The EAX register contains the response code from the message box. It is one of the ID symbols defined in the SHELL.INC file.

Uses

EAX, Flags


Virtual Sound Device

VSD_Bell	Beeps

VSD_Get_Version	Returns version number


VSD_Bell
include vsd.inc

VxDcall VSD_Bell

The VSD_Bell service generates a warning beep. This service is intended to be used when the user presses an invalid key or when an error occurs. This service produces a 1/2 second tone but it returns immediately (it does not busy wait).

This service has no parameters.

Returns

This service has no return value.

Uses

Flags


VSD_Get_Version
include vsd.inc

VxDcall VSD_Get_Version

The VSD_Get_Version service returns the version of the Virtual Sound Device.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

The carry flag is clear.

Uses

EAX, Flags


Virtual Timer Device

VTD_Begin_Min_Int_Period	Sets interrupt frequency

VTD_Disable_Trapping	Disables I/O trapping on timer ports

VTD_Enable_Trapping	Enables I/O trapping on timer ports

VTD_End_Min_Int_Period	Restores interrupt frequency

VTD_Get_Interrupt_Period	Returns timer interrupt frequency

VTD_Get_Real_Time	Returns elapsed time since start of Windows

VTD_Get_Version	Returns version number

VTD_Update_System_Clock	Updates system clock


VTD_Begin_Min_Int_Period
include vtd.inc

VxDcall VTD_Begin_Min_Int_Period

The VTD_Begin_Min_Int_Period service is used by virtual devices to ensure a minimum accuracy for system timing. When this service is called, if the interrupt period specified is lower than the current timer interrupt frequency, the interrupt period will be set to the new frequency.

Parameter	Description

EAX	Specifies the desired interrupt period.

Returns

If carry clear, the interrupt period is set. Otherwise, the specified interrupt period is not valid

Comments

Until a matching call to the VTD_End_Min_Int_Period service is made, the timer interrupt frequency is guaranteed to never be slower than the value specified.

A virtual device should call this service only once before calling VTD_End_Min_Int_Period.

Typically the Begin_Min_Int_Period and End_Min_Int_Period services are used by devices such as execution profilers that need extremely accurate timing. VMM system time out services rely on the VTD to keep time. Therefore, more frequent the timer interrupts, will allow the time-out services to be more accurate.

Fast timer interrupt periods can be very, very expensive in terms of total system performance. For example, on some machines a timer interrupt of 1 millisecond will degrade total machine throughput by 10% and disk I/O by up to 50%.

Uses

Flags


VTD_Disable_Trapping
include vtd.inc

VxDcall VTD_Disable_Trapping

The VTD_Disable_Trapping service forces the VTD to stop I/O trapping on the timer ports for a specified virtual machine. The VTD_Enable_Trapping service must be called once for every call made to this service.

Parameter	Description

EBX	Specifies a virtual machine handle.

Returns

This service has no return value.

Comments

It is sometimes necessary to temporarily disable I/O trapping for virtual machine code that reads the timer in extremely tight timing loops. A good example is the hard disk BIOS code that reads the ports hundreds of times per disk transfer. The overhead of servicing the I/O traps would cause disk performance to slow to a crawl.

If this service is called N times, then VTD_Enable_Trapping must also be called N times before trapping is re-enabled. This allows nested calls to this service by more than one virtual device.

Uses

Flags


VTD_Enable_Trapping
include vtd.inc

VxDcall VTD_Enable_Trapping

The VTD_Enable_Trapping service must be called to re-enable timer I/O port trapping after calling the VTD_Disable_Trapping service. This service must be made once for every call to VTD_Disable_Trapping. Only when every disable call has been matched by a call to this service will port trapping be re-enabled.

Parameter	Description

EBX	Specifies a virtual machine handle.

Returns

This service has no return value.

Uses

Flags


VTD_End_Min_Int_Period
include vtd.inc

VxDcall VTD_End_Min_Int_Period

The VTD_End_Min_Int_Period service allows a device to remove a timer interrupt period that it set earlier through the VTD_Begin_Min_Int_Period service.

Parameter	Description

EAX	Specifies a value passed earlier to Begin_Begin_Min_Int_Period.

Returns

If carry flag is clear, the interrupt period request was removed successfully. Otherwise, the specified interrupt period is not valid.

Uses

Flags

See Also

VTD_Begin_Min_Int_Period


VTD_Get_Interrupt_Period
include vtd.inc

VxDcall VTD_Get_Interrupt_Period

The VTD_Get_Interrupt_Period service returns the current timer interrupt frequency.

This service has no parameters.

Returns

The EAX register specifies the length of time between ticks in milliseconds.

Uses

Flags


VTD_Get_Real_Time
include vtd.inc

VxDcall VTD_Get_Real_Time

The VTD_Get_Real_Time service returns the number of real time clock ticks that have elapsed since the current Windows session was started.

This service has no parameters.

Returns

The EDX:EAX register pair contains the current system time based on an unit of 0.8 microseconds.

The EDX register contains the high doubleword of the time and EAX the low doubleword.

Uses

EAX, EDX, Flags


VTD_Get_Version
include vtd.inc

VxDcall VTD_Get_Version

The VTD_Get_Version service returns the version number and the range of interrupt periods allowed by this virtual device.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

The EBX register contains the fastest possible interrupt period in milliseconds.

The ECX register contains the slowest possible interrupt period in milliseconds.

The carry is flag clear.

Uses

EAX, EBX, ECX, Flags


VTD_Update_System_Clock
include vtd.inc

VxDcall VTD_Update_System_Clock

The VTD_Update_System_Clock service should only be called by the VMM. Virtual devices should call the Get_System_Time service. The VMM calls this service to update the system clock.

This service has no parameters.

Returns

This service has no return value.

Uses

Flags


Virtual V86 Mode Memory Manager

V86MMGR_Allocate_Buffer	Allocates from the translation buffer

V86MMGR_Allocate_V86_Pages	Allocates and maps V86 pages

V86MMGR_Free_Buffer	Frees a buffer

V86MMGR_Free_Page_Map_Region	Unmaps pages

V86MMGR_Get_EMS_XMS_Limits	Returns memory limits

V86MMGR_Get_Mapping_Info	Returns page map information

V86MMGR_Get_Version	Returns version number

V86MMGR_Get_VM_Flat_Sel	Returns selector for V86 memory

V86MMGR_Get_Xlat_Buff_State	Location and size of translation buffer

V86MMGR_GetPgStatus	Returns page status

V86MMGR_Load_Client_Ptr	Loads client pointer

V86MMGR_LocalGlobalReg	Specifies local or global memory

V86MMGR_Map_Pages	Maps pages across virtual machines

V86MMGR_ResetBasePages	Used by MS-DOS manager

V86MMGR_Set_EMS_XMS_Limits	Sets memory limits

V86MMGR_Set_Mapping_Info	Sets mapping information

V86MMGR_Set_Xlat_Buff_State	Sets location and size of buffer

V86MMGR_SetAvailMapPgs	Makes V86 memory available

V86MMGR_SetLocalA20	Sets scope of A20

V86MMGR_Xlat_API	Executes scripts


V86MMGR_Allocate_Buffer
include v86mmgr.inc

VxDcall V86MMGR_Allocate_Buffer

The V86MMGR_Allocate_Buffer service allocates a portion of the current virtual machine's  translation buffer and optionally copies data from the protected-mode pointer in FS:ESI registers into the allocated buffer.

Parameter	Description

EBX	Specifies the current virtual machine handle. The current virtual machine must be in protected mode.

EBP	Points to a Client_Reg_Struc structure containing the register values of the current virtual machine.

ECX	Specifies the number of bytes to allocate.

FS:ESI	Specifies a pointer to the extended memory to copy. If the carry flag is set, the service copies the source buffer into a V86 buffer; otherwise, it copies the source buffer into V86 memory.

Returns

The carry flag is clear if the service is successful. The ECX register contains the actual number of bytes allocated ( less than or equal to the original ECX parameter). The high word of the EDI register contains the V86 segment for the translation buffer and the low word of the EDI register contains the offset of the allocated buffer.

If the carry flag is set, the service could not allocate buffer.

Comments

This service maps fewer bytes than the value specified in the ECX parameter if the length of the buffer would extend past the FS segment limit. Therefore, a virtual device needs to preserve the value returned in ECX from this service to use when deallocating the buffer using the V86MMGR_Free_Buffer service.

The buffers are maintained as a stack. Therefore, the last buffer allocated must be the first buffer freed.

Uses

ECX, EDI, Flags


V86MMGR_Allocate_V86_Pages
include v86mmgr.inc

VxDcall V86MMGR_Allocate_V86_Pages

The V86MMGR_Allocate_V86_Pages service allocates and maps the base V86 memory for a virtual machine.

Parameter	Description

EBX	Specifies the virtual machine handle.

ESI	Specifies the desired size of virtual machine address space in kilobytes.

EDI	Specifies the minimum size of virtual machine address space in kilobytes.

ECX	Specifies the flags. See the V86MMGR.INC file for bit definitions.

Returns

The carry flag is clear if the service allocates memory and maps it into the virtual machine. The EAX register contains the actual number of pages allocated and mapped (that is, the size of the virtual machine). This size does not include the space from 0 to the first virtual machine page.

If the carry flag is set, the service could not allocate memory.

Comments

On an error, this service calls the GetSetDetailedVMError service to set an error value.

The sizes specified by the ESI and EDI parameters include the region of V86 address space from 0 through the first virtual machine page.

Uses

EAX, Flags


V86MMGR_Free_Buffer
include v86mmgr.inc

VxDcall V86MMGR_Free_Buffer

The V86MMGR_Free_Buffer service deallocates a buffer that was allocated by the V86MMGR_Allocate_Buffer service. It will optionally copy data from the translation buffer to the buffer pointed to by FS:ESI.

The buffers are maintained as a stack. Therefore, the last buffer allocated must be the first buffer freed.

Parameter	Description

EBX	Specifies the current virtual machine handle. The current virtual machine must be in protected mode.

EBP	Points to a Client_Reg_Struc structure containing the register values of the current virtual machine.

ECX	Specifies the number of bytes to free (returned from the V86MMGR_Allocate_Buffer service).

FS:ESI	Specifies a pointer to an extended memory buffer. If the carry flag is set, the service copies the buffer from V86 memory; otherwise, it does not copy the buffer.

Returns

This service has no return value.

Uses

Flags


V86MMGR_Free_Page_Map_Region
include v86mmgr.inc

VxDcall V86MMGR_Free_Page_Map_Region

The V86MMGR_Free_Page_Map_Region service unmap pages that were mapped by the V86MMGR_Map_Pages service.

Parameter	Description

ESI	Specifies the map handle to free.

Returns

This service has no return value.

Comments

After a call to this service, the old map buffer address contains null memory is invalid and the ESI register is undefined.

Uses

ESI, Flags


V86MMGR_Get_EMS_XMS_Limits
include v86mmgr.inc

VxDcall V86MMGR_Get_EMS_XMS_Limits

The V86MMGR_Get_EMS_XMS_Limits service returns the current EMS and XMS limits.

Parameter	Description

EBX	Specifies the virtual machine handle to get limits of.

Returns

The following register contain values:

Register	Description

EAX	Minimum EMS kilobytes (multiple of 4)

EDX	Maximum EMS kilobytes (multiple of 4)

ESI	Minimum XMS kilobytes (multiple of 4)

EDI	Maximum XMS kilobytes (multiple of 4)

ECX	Access to HMA is disabled (if zero) or enabled (if 1).

Uses

All registers except EBX, EBP, and segment registers


V86MMGR_Get_Mapping_Info
include v86mmgr.inc

VxDcall V86MMGR_Get_Mapping_Info

The V86MMGR_Get_Mapping_Info service returns information about the current page mapping areas.

This service has no parameters.

Returns

The CH register contains the total number of pages reserved for global mapping and the CL register contains the number of pages available (not in use) for global mapping.

Uses

ECX, Flags


V86MMGR_Get_Version
include v86mmgr.inc

VxDcall V86MMGR_Get_Version

The V86MMGR_Get_Version service returns the V86MMGR version number.

This service has no parameters.

Returns

The AH register contains the major version number.

The AL register contains the minor version number.

The carry flag is clear.

Uses

EAX, Flags


V86MMGR_Get_VM_Flat_Sel
include v86mmgr.inc

VxDcall V86MMGR_Get_VM_Flat_Sel

The V86MMGR_Get_VM_Flat_Sel service returns a selector that points to the base of the specified virtual machine's V86 address space. This is useful for 32-bit applications since this selector can be used to point to any address in the virtual machine's V86 address space. The selector is writable and has a limit of 11000h bytes so that the high memory area is also addressable.

The selector returned is in the specified virtual machine's LDT. Therefore, the selector is only valid to use when the virtual machine is running (is the current virtual machine).

Parameter	Description

EBX	Specifies a virtual machine handle (any virtual machine handle is valid).

Returns

The EAX register contains a selector with the base at the high linear address of V86 memory (the high word is zero).

Uses

EAX, Flags


V86MMGR_Get_Xlat_Buff_State
include v86mmgr.inc

VxDcall V86MMGR_Get_Xlat_Buff_State

The V86MMGR_Get_Xlat_Buff_State service returns information about the current mapping buffer status.

Always call this service to find the segment of the translation buffer. Since the buffer can move at any time a virtual device should never make any assumptions about the size or location of the buffer.

Parameter	Description

EBX	Specifies the virtual machine handle.

Returns

The EAX register contains the V86 segment of the translation buffer; the high word is zero.

The ECX register contains the number of bytes of the buffer not in use.

The EDX register contains the total size of the buffer in bytes; the maximum size is 10000h.

Uses

EAX, ECX, EDX, Flags


V86MMGR_GetPgStatus
include v86mmgr.inc

VxDcall V86MMGR_GetPgStatus

The V86MMGR_GetPgStatus service returns the status of a page. This service allows the caller to discover various aspects of what a specific page is being used for. This service can be called with any page number in the 0 through 110h range, but it is intended to return useful information only for pages above the last V86 page.

This service is only available for Windows 3.1 and later.

Parameter	Description

EBX	Specifies the virtual machine handle to get information for. If this parameter is zero, the service retrieves global information.

ECX	Specifies the V86 page number. It must be in the rage 0 through 110h.

Returns

The EAX register contains one or more of the following information values for the page:

Value	Meaning

V86PS_MAP	Page belongs to mapper

V86PS_XMS	Page belongs to XMS driver

V86PS_EMM	Page belongs to EMM driver

V86PS_UMB	Page is part of a UMB

The V86PS_XMS value is not necessarily set.

Comments

One particular use of this service is to determine if a page is part of an imported high memory UMB.

This service will not work if called during the Sys_Critical_Init message. The service is not valid until the Device_Init message. Calls during Device_Init only return useful information if paging import from a LIMulator/UMBulator is performed. In cases where no paging import exists, the information will not be correct until after the Init_Complete message.

Uses

EAX, Flags


V86MMGR_Load_Client_Ptr
include v86mmgr.inc

VxDcall V86MMGR_Load_Client_Ptr

The V86MMGR_Load_Client_Ptr service loads the FS:ESI register with the specified client segment and offset values. If the virtual machine is running a 16-bit protected mode application, the high word of the offset in ESI is set to zero. Otherwise, if the virtual machine is running a 32-bit program or is in VxD_Exec_Mode, the high word of ESI is not set to zeroed. This allows most translation procedures to operate correctly without the need to test the execution mode of the current virtual machine.

Parameter	Description

AH	Specifies a client segment register.

AL	Specifies a client offset register.

EBX	Specifies the current virtual machine handle. The virtual machine must be in protected mode.

EBP	Points to a Client_Reg_Struc structure containing the register values for the virtual machine.

Returns

The FS:ESI register pair points to the client's buffer.

Example

The value passed in AX should be formed from the Client_Reg_Struc structure fields. For example, to load the virtual machine's DS:(E)DX, use the following code:

mov ax, (Client_DS * 100h) + Client_DX

VxDcall V86MMGR_Load_Client_Ptr

Uses

FS, ESI, Flags


V86MMGR_LocalGlobalReg
include v86mmgr.inc

VxDcall V86MMGR_LocalGlobalReg

The V86MMGR_LocalGlobalReg service specifies whether the indicated V86 memory region is local or global memory. This VMM memory manager calls this service whenever the TestGlobalV86Mem service is called.

This service is only available for Windows 3.1 and later.

Parameter	Description

EDX	Specifies the page number of the start of the region.

EDI	Specifies the page number of the end of the region.

Returns

The EAX register contains one of the following values:

Value	Meaning

0	Page range is local

1	Page range is global

2	Page range is partially global and partially local

3	Page range is unknown

Comments

This service is intended to support UMBs. UMB regions are local or global depending on the free per virtual machine UMB list.

Uses

EAX, Flags


V86MMGR_Map_Pages
include v86mmgr.inc

VxDcall V86MMGR_Map_Pages

The V86MMGR_Map_Pages service maps the specified buffer into every virtual machine at the same address using page mapping. If the contents of memory are changed in one virtual machine the change will be reflected in the original buffer as well in all other virtual machines.

If the address specified in ESI is zero, no memory is mapped, but a global linear address range is allocated. It is then up to the caller to map appropriate pages into virtual machines. Use the linear address returned in EDI for the base page to map memory into.

Parameter	Description

ESI	Points to the linear address to map. If this parameter is zero, the service reserves the map region without mapping memory.

ECX	Specifies the number of bytes to map.

Returns

If the carry flag is clear, the memory is mapped. The ESI register contains the map handle (used to free the map region), and the EDI register contains the linear address of map buffer. It is less than 1 megabyte.

If the carry flag is set, the service could not map the memory.

Uses

ESI, EDI, Flags


V86MMGR_ResetBasePages
include v86mmgr.inc

VxDcall V86MMGR_ResetBasePages

The V86MMGR_ResetBasePages service is used by the virtual MS-DOS manager to manipulate MS-DOS related memory associated with the base memory handle of a virtual machine.

Parameter	Description

EBX	Specifies the virtual machine handle.

ECX	Specifies the count of pages to manipulate.

EAX	Specifies the Linear or physical page number of first page to manipulate.

Returns

If carry flag is set if the service could not manipulate the base handle.

Uses

Flags


V86MMGR_Set_EMS_XMS_Limits
include v86mmgr.inc

VxDcall V86MMGR_Set_EMS_XMS_Limits

The V86MMGR_Set_EMS_XMS_Limits service sets the EMS and XMS memory limits for a virtual machine. This service must be made during the Create_VM message for it to work properly. This service should not be called on the system virtual machine.

Parameter	Description

EBX	Specifies the handle of the virtual machine to set limits for.

EAX	Specifies minimum EMS kilobytes.

EDX	Specifies the maximum EMS kilobytes.

ESI	Specifies the minimum XMS kilobytes.

EDI	Specifies the maximum XMS kilobytes.

ECX	Specifies the flag. See the V86MMGR.INC file for flag definitions.

Returns

If carry flag is set, the service could not set limits or there was insufficient memory for the minimum allocation request. In this case, some of the limits may have been set. Use the V86MMGR_Get_EMS_XMS_Limits service to determine the new settings.

Comments

This service calls the GetSetDetailedVMError service to set error values.

To disable access to XMS or EMS memory, set maximum and minimum values to zero.

To set only one of the two limits, set the other maximum and minimum to -1.

The XMS limit does not include the HMA.

Uses

Flags


V86MMGR_Set_Mapping_Info
include v86mmgr.inc

VxDcall V86MMGR_Set_Mapping_Info

The V86MMGR_Set_Mapping_Info service notifies the V86MMGR mapper services of the amount of space a virtual device requires for calls to the mapper service calls. This service must be made during the Sys_Critical_Init or Device_Init message for devices with an init order less than V86MMGR_Init_Order. These settings are used by during the V86MMGR Device_Init message.

Parameter	Description

AL	Specifies the minimum number of pages (4K) required for copy buffer.

AH	Specifies the maximum number of pages (4K) desired for copy buffer.

BL	Specifies the minimum number of pages required for private global mapping region.

BH	Specifies the minimum number of pages required for shared global mapping region.

CL	Specifies the maximum number of pages desired for global page mapping region.

Returns

This service has no return value.

Uses

Flags


V86MMGR_Set_Xlat_Buff_State
include v86mmgr.inc

VxDcall V86MMGR_Set_Xlat_Buff_State

The V86MMGR_Set_Xlat_Buff_State service switches to an alternate mapping buffer. This feature is provided for protected-mode TSR programs which may need to switch to a private translation buffer before executing protected mode MS-DOS calls since the default buffer may be full.

A virtual device should get the current translation buffer state, set the new state, perform any MS-DOS call, and then set the state back to the original values.

Parameter	Description

EBX	Specifies a virtual machine handle (any virtual machine handle valid).

EAX	Specifies the V86 segment of the translation buffer; high word is zero.

ECX	Specifies the number of bytes of the buffer not in use.

EDX	Specifies the total size of the buffer in bytes; maximum size is 10000h.

Returns

This service has no return value.

Uses

Flags


V86MMGR_SetAvailMapPgs
include v86mmgr.inc

VxDcall V86MMGR_SetAvailMapPgs

The V86MMGR_SetAvailMapPgs service relinquishes regions above the last V86 page to the V86MMGR's mapper services for use as a mapper region.

This service is only available for Windows 3.1 and later.

Parameter	Description

EAX	Specifies the starting page number of the region.

ECX	Specifies the size of the region in pages.

Returns

The carry flag is clear if the service adds the region. Otherwise, the carry flag is set to indicate an error such as an invalid region.

Comments

Virtuals devices other than the V86MMGR (DOSMGR) can relinquish regions above the last V86 page to the V86MMGR's mapper services for use as a mapper region. These regions usually overlap with V86MMGR XMS UMB import pages, but this is not required. A virtual device can hand over a page that it has already marked as owned by the device in the Device_V86_Pages array. The V86MMGR marks the page as one it owns (even though it did not actually do the _Assign_Device_V86_Pages for it).

Once a region is relinquished, the virtual device must not attempt to access it. it. These regions may only be marked as in-use by the V86MMGR XMS driver. This happens when the region overlaps XMS UMB import pages.

This routine has a global effect, it does not take a virtual machine handle argument.

Uses

Flags


V86MMGR_SetLocalA20
include v86mmgr.inc

VxDcall V86MMGR_SetLocalA20

The V86MMGR_SetLocalA20 service changes the default global behavior of A20 to local if the HMA is global. This service has no effect if the HMA is not global.

This service is only available for Windows 3.1 and later.

This service has no parameters.

Returns

This service has no return value.

Comments

When there is a global HMA user, the A20 state associated with the HMA is also global. Changing A20 in a virtual machine changes it in all virtual machines simultaneously. Some global A20 users (such as MS-DOS 5.0) desire that the A20 state be local even though the HMA is global.

The V86MMGR device does a V86 Interrupt 2Fh device broadcast which also can set this state. This service is effectively a duplicate of the broadcast service which can be called by a virtual device. It is not an error if the state is set using both methods.

Uses

Flags


V86MMGR_Xlat_API
include v86mmgr.inc

VxDcall V86MMGR_Xlat_API

The V86MMGR_Xlat_API service is a simple interpreter that executes scripts that are created using macros defined in the V86MMGR.INC file.

Parameter	Description

EBX	Specifies the current virtual machine handle.

EBP	Points to a Client_Reg_Struc structure containing the register values for the virtual machine.

EDX	Points to the script to translate.

Returns

The carry flag is clear if the script has executed successfully; the EDX register is destroyed.

If the carry flag is set, the service encountered an error while executing a script.

Uses

EDX, Flags