3.2 System Control Messages

The VMM sends system control messages to a virtual device to notify it of changes that affect the system and virtual machines. Most virtual devices need to track the creation and status of virtual machines, so the VMM sends messages to the virtual device whenever a virtual machine is created, initialized, or terminated. It also sends a message when the execution focus moves to or from the virtual machine, or when the virtual shell device needs to display a message box to the user.

The following is a list of the most common messages and recommendations for how the virtual devices should process the messages:

Message Recommended Action

Begin_Message_Mode A virtual device receives this message when the virtual shell device needs to display a message box to the user but cannot use the system virtual machine and Windows functions to do so. The virtual keyboard, mouse, and display devices save their current state, enable any message mode services, and initialize the corresponding device for message mode processing.
Create_VM This is the first message the virtual device receives when a new virtual machine is created. The virtual devices should initialize data associated with the virtual machine, especially the control block.
Debug_Query A virtual device receives this message from the debugger, WDEB386. The virtual device can display a list of debugging, and read user commands from the debugging terminal.
Destroy_VM This is the third termination message a virtual device receives for a virtual machine. The Simulate_Int and Exec_Int services are not available for the given virtual machine.
Device_Init This is the second message a virtual device receives. Interrupts are enabled. Most virtual devices allocate and copy the initial state to a device-specific section in the system virtual machine's control block, install callback procedures for interrupts and I/O protection faults, and specify instance data. At this point, the Simulate_Int and Exec_Int services are available.
End_Message_Mode A virtual device receives this message when the virtual shell device no longer needs to display a message box. The virtual keyboard, mouse, and display devices restore the previously saved state of the given virtual machine, and disable any message mode services.
Init_Complete This is the third message a virtual device receives and is the last message associated with system initialization.
  Although most virtual devices do not process this message, virtual devices that use V86 memory should locate and claim this memory before returning. After a virtual device returns this message, the VMM discards the initialization code and data segments of the virtual device.
Query_Destroy A virtual device receives this message when the virtual shell device needs to determine whether a virtual machine can be destroyed. The virtual device can set the carry flag, and return to prevent the virtual machine from being destroyed. In such cases, the virtual device should notify the user of the problem by using the SHELL_Message service.
Reboot_Processor A virtual device receives this message when the user attempts to restart the computer. A virtual device, such as the keyboard device, that can restart the computer should do so.
Set_Device_Focus A virtual device receives this message when the execution focus moves from one virtual machine to another. The virtual device restores the hardware device to the state associated with the virtual machine. If the virtual device used I/O trapping to manage the virtual machine when it did not have the execution focus, the virtual device should remove as much I/O trapping as possible, and let the virtual machine run as fast as possible.
Sys_Critical_Exit This is the last message sent to a virtual device. Interrupts are disabled and the Simulate_Int and Exec_Int services are not available. Virtual devices should reset their associated hardware device to ensure a trouble-free return to real mode.
Sys_Critical_Init This is the first message a virtual device receives. Interrupts are not yet enabled, so the virtual device should carry out its tasks as quickly as possible. Most virtual devices do the following:
  Install and initialize any functions needed to support hardware interrupts from the device and software interrupts from the VMM or other virtual devices.
  Claim for exclusive use any V86-mode memory pages needed for the device. For example, the virtual display device claims the video memory.
  Initialize any data needed by the virtual device's services. This may include reading settings from the SYSTEM.INI file.
  While processing this message, the Simulate_Int and Exec_Int services must not be used.
Sys_VM_Init A virtual device receives this message after the Init_Complete message. The virtual device should initialize the state of the hardware and software in the system virtual machine. If the virtual device sets the carry flag and returns, the VMM terminates all further processing and exits Windows.
Sys_VM_Terminate This is the first termination message a virtual device receives for the system virtual machine. The virtual device can begin preparing for termination of the virtual machine. The Simulate_Int and Exec_Int services are available. The system virtual machine is always the last virtual machine to be terminated.
System_Exit This is the first message a virtual device receives when the system is terminating. The VMM sends it after sending the Sys_VM_Terminate message. Interrupts are enabled, but the Simulate_Int and Exec_Int services are not available. If this message was sent as a result of a fatal error, the virtual device can modify the system virtual machine memory to restore the system state and allow Windows to terminate without hanging.
VM_Critical_Init This is the second message the virtual device receives when a new virtual device is created. The virtual device can set the carry flag and return to prevent the virtual machine from being created. Interrupts are disabled and the Simulate_Int and Exec_Int services are not available.
VM_Init This is the third message the virtual device receives when a new virtual device is created. The virtual device should initialize the state of the hardware and software in the virtual machine. For example, the virtual display device executes an Interrupt 10h function to set the initial display mode.
VM_Not_Executeable This is the second termination message a virtual device receives for a virtual machine. (If the virtual machine is being destroyed by the virtual shell device, this is the first message received.) The virtual device can determine the cause of the termination by checking the flags in the EDX register. The Simulate_Int and Exec_Int services are not available for the given virtual machine.
VM_Resume A virtual device receives this message when execution of the virtual machine is resumed, such as when switched to the foreground. The virtual device should lock any resources, and prepare internal structures for resumption of the virtual machine. If the virtual device sets the carry flag and returns, the VMM does not resume execution of the virtual machine.
VM_Suspend A virtual device receives this message when execution of the virtual machine has been suspended, such as when
  switched to the background. The virtual device should unlock any resources associated with the virtual machine.
VM_Terminate This is the first termination message a virtual device receives for a virtual machine. The virtual device can begin preparing for termination of the virtual machine. The Simulate_Int and Exec_Int services are available.