Call_When_VM

Call_When_VM_Returns

include vmm.inc

mov     eax, TimeOut            ; milliseconds until time out
mov     edx, RefData            ; reference data
mov     esi, OFFSET32 Callback  ; address of callback function
VMMcall Call_When_VM_Returns

Installs a callback function that receives control when a virtual machine executes the iret instruction for the current interrupt. Uses Client_CS, Client_EIP, Flags.

No return value.

TimeOut

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

Reference data to be passed to the callback procedure. Can be any 32-bit value, but is typically the address of a driver-defined structure.

Callback

Address of the callback procedure. For more information about the callback procedure, see below.

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.

Note

The preceding description implies that the only meaningful place to use Call_When_VM_Returns is when a Simulate_Far_Call or Build_Int_Stack_Frame is going to happen soon. (As noted, this is typically done inside the callback installed by Hook_V86_Int_Chain.) In particular, in order to hook the back end of a simulated interrupt, you must call Call_When_VM_Returns before the interrupt itself is simulated. If the interrupt or far call has already been simulated, Call_When_VM_Returns will not do what you want. (The name of the service is rather unfortunate. It really means "Call when the VM returns to where it is now", and not "Call when the VM executes a return instruction".)

The system calls this callback procedure as follows:

mov     ebx, VM             ; current VM handle
mov     edi, hCurThread     ; current thread handle
mov     edx, RefData        ; 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 is the value supplied when the callback procedure was installed, and the crs parameter 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 a second time. The value of the zero flag is indeterminate unless the TimeOut parameter specifies a negative value.

In other words,

(1) If you passed TimeOut = 0, then the callback is called when the VM returns and at no other time.

(2) If you passed TimeOut > 0, then the callback should begin like this:

jc      timed_out;  Timeout notification
                 ;  Otherwise, the VM returned
                 ;  before the timeout expired

(3) If you passed TimeOut < 0, then the callback should begin like this:

jc      timed_out    ;  Timeout notification
                     ;  Otherwise, the VM returned
jnz         normal_return;  VM returned with no timeout
                     ; Else, VM returned with timeout