Call_Priority_VM

Call_Priority_VM_Event

include vmm.inc

mov     eax, PriorityBoost
mov     ebx, VMHandle
mov     ecx, Flags
mov     edx, RefData
mov     esi, OFFSET32 PriorityEventCallback
mov     edi, TimeOut
VMMcall Call_Priority_VM_Event
mov     [EventHandle], esi

Calls the callback function immediately or schedules a priority event for the specified virtual machine. This is an asynchronous service. Uses Flags and ESI.

Returns zero in ESI if the callback function was called immediately. Otherwise, returns the event handle in ESI. The handle can be used in a subsequent call to the Cancel_Priority_VM_Event service to cancel the event.

PriorityBoost

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. Common priority boost values, from lowest to highest, are as follows:

Value	Meaning
Reserved_Low_Boost	Reserved for use by system.
Cur_Run_VM_Boost	Use to boost the priority of each virtual machine, in turn, forcing them to run for their allotted time slices.
Low_Pri_Device_Boost	Use for operations that need timely processing but are not time critical.
High_Pri_Device_Boost	Use for time-critical operations that should not circumvent the critical section boost.
Critical_Section_Boost	Use to boost the priority of the virtual machine whenever it enters a critical section (calls Begin_Critical_Section).
Time_Critical_Boost	Use for operations that require immediate processing, 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.

Forgetting to pass a priority value in the EAX register is a common error.

VMHandle

Handle of the virtual machine to process the event. This value must be a valid VM handle.

Flags

A combination of these action flags:

Value	Meaning
PEF_Always_Sched	Event is always scheduled, meaning the callback function is never called immediately.
PEF_Dont_Unboost	Priority of the virtual machine is not reduced after return from callback function.
PEF_Time_Out	Specifies that time-out value in the EDI register should be used. Available in Windows version 3.1 or later.
PEF_Wait_For_STI	Callback function is not called until the virtual machine enables interrupts in all threads.
PEF_Wait_Not_Crit	Callback function is not called until the virtual machine is not in a critical section or time-critical operation.
PEF_Wait_Not_Time_Crit, PEF_Wait_Not_HW_Int	Callback function is not called until the thread priority is below TIME_CRITICAL_BOOST. Useful to prevent an event from occurring while an interrupt is being simulated into a VM.

All other values are reserved.

RefData

Reference data to pass to the callback function.

EventCallback

Address of the callback function to install. For more information about the callback function, see PriorityEventCallback.

TimeOut

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

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

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

For additional information about event callbacks, see Event Callbacks.

See also Adjust_Exec_Priority, Begin_Critical_Section, Call_When_Not_Critical, Call_VM_Event, Cancel_Priority_VM_Event, PriorityEventCallback