_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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



_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.


Parameters

   nBytes
   Specifies the number of bytes to allocate.

   flags
   Specifies the operation flags. This parameter must be set to 0.


Return Value

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



_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).


Parameters

   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.


Return Value

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_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.


Parameters

   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.


Return Value

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_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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



_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.


Parameters

   nBytes
   Specifies the number of bytes to allocate.

   flags
   Specifies the operation flags. This parameter must be set to 0.


Return Value

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



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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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_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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



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.


Parameters

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


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

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


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

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


Return Value

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.


Parameters

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


Return Value

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_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.


Parameters

   TimeOut
   Specifies a handle identifying the time-out to cancel. If this parameter
   is zero, the service returns immediately (does nothing).


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

This service has no return value.


Uses

Flags


See Also

Adjust_Exec_Priority, Begin_Critical_Section, End_Critical_Section



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

   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


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

   This service has no parameters.


Return Value

This service does not return



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.


Parameters

   TokenCount
   Specifies the initial count of tokens.


Return Value

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



_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.


Parameters

   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.


Return Value

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



Destroy_Semaphore

    include vmm.inc

    mov     eax, Semaphore      ; semaphore handle
    VMMcall Destroy_Semaphore
The Destroy_Semaphore service destroys the specified semaphore.


Parameters

   Semaphore
   Specifies the handle of the semaphore to delete.


Return Value

This service has no return value.


Uses

Flags


See Also

Create_Semaphore



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.


Parameters

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


Return Value

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.


Parameters

   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.


Return Value

This service has no return value.


Uses

Flags


See Also

Enable_Local_Trapping, Install_IO_Handler, Install_Mult_IO_Handlers



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

This service has no return value.


Uses

Flags


See Also

Enable_VM_Ints



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.


Parameters

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


Return Value

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.


Parameters

   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.


Return Value

This service has no return value.


Uses

Flags


See Also

Disable_Local_Trapping, Install_IO_Handler, Install_Mult_IO_Handlers



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

   Count
   Specifies the reentrancy count previously returned by the
   Begin_Reentrant_Execution service.


Return Value

This service has no return value.


Uses

Flags


See Also

Begin_Reentrant_Execution



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

   Interrupt
   Specifies the number of the interrupt to simulate.


Return Value

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.


Parameters

   Interrupt
   Specifies the number of the interrupt to execute.


Return Value

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.


Examples

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



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.


Parameters

   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.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters


Return Value

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



_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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



_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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



_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.


Parameter

This function has no parameters.

This service has no parameters.


Return Value

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



_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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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_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.


Parameters

   VM
   Specifies a handle identifying the virtual machine in which the
   protected-mode application is running.


Return Value

The EDI register contains the address of the application control block.


Uses

EDI



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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_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.


Parameters

   Char
   Specifies the debugging option to check for.


Return Value

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



_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.


Parameters

   DemandInfo
   Points to a DemandInfoStruc structure containing information for demand
   paging.

   flags
   Specifies the operation flags. This parameter must be set to 0.


Return Value

This service has no return value.


Uses

Flags



_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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

   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.


Return Value

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_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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

The EBX register contains the handle of virtual machine that currently has
the execution focus.


Uses

EBX, Flags


See Also

Set_Execution_Focus



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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_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.


Parameters

   Interrupt
   Specifies the interrupt number of the fault to check.


Return Value

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



_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.


Parameters

   flags
   Specifies the operation flags. This parameter must be set to 0.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



_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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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_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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameter

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   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.


Return Value

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_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.


Parameters

   VM
   Specifies a handle identifying a virtual machine.


Return Value

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_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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



_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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

The EAX register contains the memory handle of the system nul page.


Uses

EAX


See Also

_MapIntoV86



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.


Parameters

   Interrupt
   Specifies the number of the interrupt to check.


Return Value

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.


Parameters

   Interrupt
   Specifies the number of the interrupt to check.


Return Value

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_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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

   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.


Return Value

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



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).


Parameters

   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.


Return Value

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



_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.


Parameters

   flags
   Specifies the operation flags. This parameter must be set to 0.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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_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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

The EBX register contains the system virtual machine handle.


Uses

EBX, Flags


See Also

Get_Cur_VM_Handle, Test_Sys_VM_Handle



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   VM
   Specifies a handle identifying the virtual machine for which to retrieve
   information.


Return Value

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



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.


Parameters

   Interrupt
   Specifies the number of the interrupt to check.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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).


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



_GetVMPgCount

    include vmm.inc

    VMMcall _GetVMPgCount, <VM, flags>
The _GetVMPgCount service returns the current count of pages allocated to a
particular virtual machine.


Parameters

   VM
   Specifies a handle identifying the virtual machine to examine.

   flags
   Specifies the operation flags. This parameter must be set to 0.


Return Value

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



_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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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_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.


Parameters

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


Return Value

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



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

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


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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_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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



_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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



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.


Parameters

   List
   Specifies the handle for the list.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

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


Return Value

This service has no return value.


Uses

ESI, Flags


See Also

List_Create



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.


Parameters

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


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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


Uses

Flags



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.


Parameters

   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.


Return Value

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.


Parameters

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


Return Value

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



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.


Parameters

   Byte
   Specifies the value of the byte to search for.


Return Value

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



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.


Parameters

   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.


Return Value

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.


Comment

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



_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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

This service has no return value.


Uses

Flags


See Also

_GetNULPageHandle



_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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to resume.


Return Value

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.


Parameters

   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.


Return Value

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



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:

o   WINDIR environment variable

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

o   Current working directory

o   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.


Parameters

   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.


Return Value

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



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.


Parameters

   Char
   Specifies the character to write to the debugging device.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   Char
   Specifies the character to write to the secondary display.

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


Return Value

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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   flags
   Specifies the operation flags. This parameter must be set to 0.


Return Value

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



_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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

   Claims
   Specifies the number of times to release ownership of critical section.
   Zero is a valid number, but is ignored.


Return Value

This service has no return value.


Uses

Flags


See Also

Claim_Critical_Section, End_Critical_Section



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

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


Return Value

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



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.


Parameters

   Buffer
   Points to the buffer containing the client state previously saved using
   the Save_Client_State service.


Return Value

This service has no return value.


Comments

This service can have the following side effects:

o   Changes the execution mode if the state being restored is in a
    different execution mode from the current one.

o   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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to resume.


Return Value

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



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.


Parameters

   Buffer
   Points to the buffer to receive the client state. The buffer must have
   the same size as a Client_Reg_Struc structure.


Return Value

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



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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to receive the
   execution focus.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



_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.


Parameters

   PgNum
   Specifies the linear page number to set the last V86 page.

   flags
   Specifies the operation flags. This parameter must be set to 0.


Return Value

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_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.


Parameters

   Column
   Specifies the column position.

   Row
   Specifies the row position.


Return Value

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



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.


Parameters

   nmi
   Points to the new NMI handler.


Return Value

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



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.


Parameters

   Entries
   Points to an array of 16 page table entries which define the physical
   HMA alias.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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_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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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

   ExitCode
   Specifies the exit code value.


Return Value

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



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.


Parameters

   Time
   Specifies the minimum time-slice granularity in milliseconds.


Return Value

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.


Parameters

   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.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

   Semaphore
   Specifies a handle identifying the semaphore to signal.


Return Value

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



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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   Bytes
   Specifies the number of bytes to pop from the stack.


Return Value

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.


Parameters

   Interrupt
   Specifies the number of the interrupt to simulate.


Return Value

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_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.


Parameters

   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.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   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.


Return Value

This service has no return value.


Uses

Client_ESP, Flags


See Also

Simulate_Pop



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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to suspend.


Return Value

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



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.


Parameters

   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.


Return Value

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



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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to test.


Return Value

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.


Parameters

   Value
   Specifies the value to test.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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


Uses

Flags



_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.


Parameters

   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.


Return Value

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



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.


Parameters

   VM
   Specifies the virtual machine handle to test.


Return Value

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



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.


Parameters

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


Return Value

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



_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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

This service has no return value.


Comments

The virtual timer device must disabled interrupts before calling this
service.


Uses

Flags



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.


Parameters

   VM
   Specifies the virtual machine handle to test.


Return Value

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


Uses

Flags


See Also

Test_Cur_VM_Handle, Test_Sys_VM_Handle



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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to restore.


Return Value

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



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.


Parameters

   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.


Return Value

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



_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.


Parameters

   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.


Return Value

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



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



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



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.


Members

   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



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.


Members

   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.


Members

   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



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.


Parameters

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


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   VM
   Specifies a handle identifying the new virtual machine.


Return Value

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.


Parameters

This function has no parameters.

This message has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This message has no parameters.


Return Value

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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to destroy.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

This function has no parameters.

This message has no parameters.


Return Value

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.


Parameters

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


Return Value

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.


Parameters

   VM
   Specifies a handle identifying the current virtual machine.

   abc
   Points to an application control block.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to destroy.


Return Value

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.


Parameters

This function has no parameters.

This message has no parameters.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

This function has no parameters.

This message has no parameters.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   SysVM
   Specifies a handle identifying the system virtual machine.


Return Value

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.


Parameters

   SysVM
   Specifies a handle identifying the system virtual machine.


Return Value

The carry flag must be clear.


Comment

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.


Parameters

   SysVM
   Specifies a handle identifying the system virtual machine.


Return Value

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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to create.


Return Value

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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to create.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to resume.


Return Value

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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to suspend.


Return Value

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.


Parameters

   VM
   Specifies a handle identifying the virtual machine to terminate.


Return Value

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



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.


Parameters

   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


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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_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.


Parameters

   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



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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



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.


Parameters

   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


Return Value

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



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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

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


Return Value

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.


Parameters

This function has no parameters.

This macro has no parameters.


Return Value

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.


Parameters

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


Return Value

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.


Parameters

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


Return Value

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.


Parameters

   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.


Return Value

This macro has no return value.


See Also

Begin_Service_Table



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.


Parameters

   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.


Parameters

   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.


Return Value

This macro never returns.


Examples

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.


Parameters

This function has no parameters.

This macro has no parameters.


Return Value

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.


Parameters

   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.


Return Value

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.


Examples

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.


Parameters

   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.


Return Value

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.


Examples

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.


Parameters

This function has no parameters.

This macro has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This macro has no parameters.


Return Value

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.


Parameters

   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.


Return Value

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.


Examples

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.


Parameters

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

   Compare
   Specifies the value to compare


Return Value


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.


Parameters

   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.


Return Value

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.


Examples

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

This function has no parameters.

This macro has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This macro has no parameters.


Return Value

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.


Parameters

   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.


Parameters

This function has no parameters.

This macro has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This macro has no parameters.


Return Value

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.


Parameters

   Int_Number
   Specifies the number of the software interrupt to execute.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

This function has no parameters.

This macro has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This macro has no parameters.


Return Value

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.


Parameters

   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.


Parameters

This function has no parameters.

This macro has no parameters.


Return Value

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

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.


Members

   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



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_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_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.


Return Value

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.


Members

   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_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.


Parameters

   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.


Return Value

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



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.


Members

   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



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.


Parameters

   DriveNum
   Specifies an Interrupt 13h drive number.


Return Value

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



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.


Parameters

This function has no parameters.

This service has no entry parameters.


Return Value

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_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.


Parameters

   This service has no entry parameters.


Return Value

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.


Parameters

   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.



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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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



DOSMGR_Add_Device

    include dosmgr.inc

    VxDcall DOSMGR_Add_Device
The DOSMGR_Add_Device service adds a device to the device list.


Parameters

   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).


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   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.


Return Value

The carry flag is clear if the device is instanced. Otherwise, the carry
flag is set to indicate one of the following errors:

o   No device with this name in device list

o   Device is in MS-DOS RAM BIOS (Segment of device == 70h)

o   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.


Parameters

   EDX
   Specifies the page number of the start of the region.

   EDI
   Specifies the page number of the end of the region.


Return Value

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


Parameters

   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).


Return Value

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



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   AL
   Specifies the drive number (0 = A, 1 = B, etc.)

   EBX
   Specifies the handle of the virtual machine to check.


Return Value

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



_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.


Parameters

   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.


Return Value

This service has no return value.


Comments

This service must be called before calling the _DOSMGR_Exec_VM service.


See Also

_DOSMGR_Exec_VM



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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   This service has no parameters.


Return Value

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



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.


Members

   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.



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.


Parameters

   EDI
   Points to a Block Device Descriptor.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

This service has no return value.


Uses

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



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.


Parameters

   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


Return Value

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



SHELL_Event

    include shell.inc

    VxDcall SHELL_Event
The SHELL_Event service posts an event in the Windows shell to VMDOSAPP.


Parameters

   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.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   EBX
   Specifies the handle of the virtual machine to examine.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   ESI
   Specifies the map handle to free.


Return Value

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.


Parameters

   EBX
   Specifies the virtual machine handle to get limits of.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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).


Parameters

   EBX
   Specifies a virtual machine handle (any virtual machine handle is
   valid).


Return Value

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.


Parameters

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   EDX
   Specifies the page number of the start of the region.

   EDI
   Specifies the page number of the end of the region.


Return Value

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.


Parameters

   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.


Return Value

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_NoUMBInitCalls

    include v86mmgr.inc

    VxDcall V86MMGR_NoUMBInitCalls
The V86MMGR_NoUMBInitCalls service supports QEMM version 5.x. This service
is called by the VMM before the SyS_Critical_Init message is done, and
allows the XMSUMBINITCALLS=FALSE setting in the SYSTEM.INI file.

This service is only available for Windows 3.1 and later.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

This service has no return value.



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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   EAX
   Specifies the starting page number of the region.

   ECX
   Specifies the size of the region in pages.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   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.


Return Value

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



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.


Parameters

   EAX
   Specifies the hardware COM port number. It must be in the range 1 to 4.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   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).


Return Value

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.


Parameters

   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.


Return Value

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



VDD_Clear_Mod

    include vdd.inc

    VxDcall VDD_Clear_Mod
The VDD_Clear_Mod service clears the change state of a virtual machine.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   EAX
   Specifies whether the cursor should be hidden (nonzero) or displayed
   (zero).

   EBX
   Specifies a pointer to the control block.


Return Value

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.


Parameters

   EAX
   Specifies the color. For EGA/VGA driver, this parameter is a text mode
   attribute.

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   EBX
   Specifies the virtual machine handle.

   EAX
   Specifies the background attribute.


Return Value

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.


Parameters

   EAX
   Specifies the color. For EGA/VGA drivers, this parameter is a text mode
   attribute.

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   EAX
   Specifies the row position.

   EDX
   Specifies the column position.

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   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


Return Value

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.


Parameters

   EBX
   Specifies the virtual machine handle.

   AX
   Specifies the PIF bits.


Return Value

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.


Parameters

   EBX
   Specifies the address of the control block.


Return Value

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.


Parameters

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

This service has no return value.


Uses

EAX, Flags



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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   EAX
   Specifies the DMA handle.

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   EAX
   Specifies the DMA handle.

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   EAX
   Specifies the DMA handle.

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   EAX
   Specifies the channel number. It must be in the range 0 to 7.

   EBX
   Specifies the DMA handle.


Return Value

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

Parameters

   EAX
   Specifies the DMA handle.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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)


Parameters

   EAX
   Specifies the DMA handle.

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   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


Return Value

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.


Parameters

   EAX
   Specifies the DMA handle.


Return Value

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.


Parameters

   EBX
   Specifies the buffer identifier.


Return Value

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.


Parameters

   ESI
   Specifies the linear address of the actual DMA region.

   ECX
   Specifies the number of bytes in the DMA region.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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


Return Value

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.


Parameters

   EAX
   Specifies the DMA handle.

   EBX
   Specifies the virtual machine handle.

   DL
   Specifies the mode.

   DH
   Specifies the extended mode.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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).


Return Value

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.


Parameters

   ESI
   Specifies the linear address of the actual DMA region.

   ECX
   Specifies the number of bytes in the DMA region.


Return Value

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.


Parameters

   EAX
   Specifies the DMA handle.

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   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.


Return Value

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.



VHD_Allocate_Handle

    include vhd.inc

    VxDcall VHD_Allocate_Handle
The VHD_Allocate_Handle service allocates a handle for an operation.


Parameters

   ESI
   Specifies the address to call when the operation completes. If this
   parameter is zero, the address is not called.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   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.


Return Value

This service has no return value.



VHD_Write

    include vhd.inc

    VxDcall VHD_Write
The VHD_Write service writes to the device.


Parameters

   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.


Return Value

This service has no return value.



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.


Parameters

   IRQHand
   Specifies the handle for the interrupt request.

   VM
   Specifies the handle of the current virtual machine.


Return Value

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



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.


Parameters

   IRQHand
   Specifies the handle identifying the interrupt request.

   VMId
   Specifies the handle identifying the current virtual machine.


Return Value

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.



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.


Parameters

   IRQHand
   Specifies the handle identifying the interrupt request.

   VM
   Specifies the handle identifying the current virtual machine.


Return Value

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.



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.


Parameters

   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.


Return Value

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.



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.


Parameters

   IRQHand
   Specifies the handle identifying the interrupt request.

   VM
   Specifies the handle identifying the current virtual machine.


Return Value

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



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.


Parameters

   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).


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   ESI
   Points to a buffer of scan codes.

   ECX
   Specifies the number of scan codes in the buffer.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   EAX
   Specifies the hot key handle.

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   EAX
   Specifies the hot key handle.

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   EBX
   Specifies virtual machine handle


Return Value

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.


Parameters

   EAX
   Specifies the hot key handle.

   EBX
   Specifies the virtual machine handle.

   CX
   Specifies the required shift state.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   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.


Return Value

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



VMCPD_Get_Version

    include vmcpd.inc

    VxDcall VMCPD_Get_Version
The VMCPD_Get_Version service returns the VMCPD version number.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   EBX
   Specifies the virtual machine handle.


Return Value

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.


Parameters

   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.


Return Value

This service has no return value.


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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   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).


Return Value

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



VMPoll_Enable_Disable

    include vmpoll.inc

    VxDcall VMPoll_Enable_Disable
The VMPoll_Enable_Disable service enables or disables polling of the
specified virtual machine.


Parameters

   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.


Return Value

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.


Parameters

   This service has no parameters.


Return Value

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.


Parameters

   EBX
   Specifies the handle of the virtual machine to disable idle detection
   for.


Return Value

This service has no return value.


Uses

Flags



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.


Parameters

   lpfnVPICD
   Specifies the entry point address of the API handler for the virtual PIC
   device.


Return Value

The carry flag is clear and the AX register contains the major and minor
version numbers, if the function is successful.



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.


Parameters

   Callback
   Points to the callback procedure. When the system calls the procedure,
   the EBX register contains the handle of the current virtual machine.


Return Value

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.


Parameters

   IRQHand
   Specifies the handle of the IRQ to clear.

   VM
   Specifies the handle of the VM.


Return Value

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.


Parameters

   IRQHand
   Specifies the handle of a virtualized IRQ.


Return Value

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.


Parameters

   VecNum
   Specifies an interrupt vector number.


Return Value

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.


Parameters

   IRQNum
   Specifies an IRQ number.

   VM
   Specifies the handle identifying the virtual machine.


Return Value

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.


Parameters

   IRQHand
   Specifies the handle of the IRQ to unvirtualize.


Return Value

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.


Parameters

   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.


Return Value

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.


Parameters

   IRQHand
   Specifies the handle identifying the IRQ for which to receive status.

   VM
   Specifies the handle identifying the virtual machine.


Return Value

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.


Parameters

   IRQNum
   Specifies the number of the IRQ for which to retrieve status.


Return Value

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.


Parameters

   IRQHand
   Specifies the handle identifying the IRQ for which to receive status.

   VM
   Specifies the handle identifying the virtual machine.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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_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.


Parameters

   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.


Return Value

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_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.


Members

   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.



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.


Parameters

   IRQHand
   Specifies the handle identifying the IRQ.


Return Value

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.


Parameters

   IRQHand
   Specifies the handle identifying the IRQ.


Return Value

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.


Parameters

   IRQHand
   Specifies the handle identifying the IRQ.


Return Value

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_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.


Parameters

   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.


Return Value

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



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.


Parameters

   IRQHand
   Specifies the handle identifying the IRQ.


Return Value

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.


Parameters

   IRQHand
   Specifies the handle identifying the IRQ to set.

   VM
   Specifies the handle identifying the virtual machine.


Return Value

This service has no return value.


Comments

The interrupt is not simulated immediately if any of the following
conditions are present:

o   The virtual machine has interrupts disabled

o   The virtual machine has masked the IRQ

o   A higher priority virtual IRQ is in service

o   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.


Parameters

   IRQHand
   Specifies the handle identifying the IRQ.


Return Value

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.


Parameters

   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.


Return Value

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



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).


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

   This service has no parameters.


Return Value

The AH register contains the major version number.

The AL register contains the minor version number.

The carry flag is clear.


Uses

EAX, Flags



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.


Parameters

   EAX
   Specifies the desired interrupt period.


Return Value

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.


Parameters

   EBX
   Specifies a virtual machine handle.


Return Value

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.


Parameters

   EBX
   Specifies a virtual machine handle.


Return Value

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.


Parameters

   EAX
   Specifies a value passed earlier to Begin_Begin_Min_Int_Period.


Return Value

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.


Parameters

   This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

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.


Parameters

This function has no parameters.

This service has no parameters.


Return Value

This service has no return value.


Uses

Flags

