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. For more information about the callback procedure, see the following “Comments” section.

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

Uses

Client_CS, Client_EIP, Flags

See Also

Hook_V86_Int_Chain