VCOMM Port Driver Power Management Interface
Introduction
Important: Before you implement the interfaces described in this document, you must read and understand the VxD power management architecture described in Device Power Management for VxDs.
In Microsoft Windows 98, the power management policy owner for communications devices is Vcomm.vxd (VCOMM). As described in Communications Device Class Power Management Specification, the policy for communications devices can be expressed by a few simple rules:
| • | When the COM port is opened, VCOMM puts the device in the D0 state |
| • | When the COM port is closed, VCOMM puts the device in the D3 state |
| • | When the system is put to sleep, VCOMM puts the COM port in the D3 state (or, if it supports wake-up only in the D0 state, it is left in the D0 state) |
In the OnNow architecture, device drivers are responsible for saving and restoring device context during power state transitions. For devices that appear to the operating system as standard 16550 Universal Asynchronous Receiver/Transmitter devices, the Microsoft-provided VCOMM and Serial.vxd drivers save and restore device context. However, for other communications devices, such as controllerless modems, the IHV must provide a device-specific serial port driver to save and restore this context. This document describes the interface that VCOMM uses to inform device-specific serial port drivers of power management events so that they can save and restore context correctly.
Overview
VCOMM uses the PortEscapeFunction interface to notify port drivers of the power management events; the interface used for each event is listed in the following table.
| Interface | Event |
PM_ARM_WAKEUP | Enable wake-up |
PM_CANCEL_Dx | Cancel power state transition |
PM_DISARM_WAKEUP | Disable wake-up |
PM_QUERY_Dx | Query power state |
PM_SET_Dx | Set power state |
VCOMM sends these commands to the port driver only when it receives the analogous message from the Configuration Manager.
Note: Though Vcomm.h includes command definitions for the D1 and D2 power states, these power states are not implemented in VCOMM at this time. VCOMM will only send commands for the D0 and D3 power states.
Opening and Closing the COM Device
Because a communications device is powered on and off when the COM port is opened and closed, the port driver must perform a particular sequence of actions to make sure that the device is powered on or off at the right time. The following describes sequences for opening and closing a COM port must be strictly followed to ensure that the device works properly.
Opening the COM Port
Because of its architecture, VCOMM cannot call the port driver with a PM_SET_D0 command until the port driver completes its OpenComm command. However, most port drivers must access hardware in order to complete OpenComm. Thus, port drivers must treat the OpenComm command as an implicit PM_SET_D0 command and perform the same actions it would in response to PM_SET_D0. The following sequence must be followed when the port driver receives an OpenComm command:
1. | The port driver must perform the actions required to turn on the device (if there are any) |
2. | Then the port driver processes the OpenComm command as it normally does |
Closing the COM Port
Similar to opening a COM port, a command to close a COM port must be treated as an implicit PM_SET_D3 command. The following sequence must be followed when the port driver receives a Close command:
1. | The port driver processes the Close command as it normally does |
2. | Then the port driver must perform the actions required to turn off the device (if there are any) |
VCOMM Port Driver PM Commands
This section provides more information about the PM commands that a port driver can receive from VCOMM. VCOMM uses the PortEscapeFunction interface to notify port drivers of the power management events.
PM_QUERY_Dx
A PM_QUERY_Dx command is sent to the port driver when VCOMM receives a CONFIG_APM_QUERY_Dx message from the Configuration Manager. VCOMM sends a PM_QUERY_Dx command only when the system is preparing to enter a system-wide sleeping state.
Port drivers return PM_SUCCESS to allow the system to sleep, or PM_FAILURE to prevent the computer from sleeping. For example, the prototype for the PortEscapeFunction, shown in Vcomm.h, is PortEscapeFunction { hPort DWORD Function DWORD Indata DWORD Outdata DWORD }
The port receives the PM_QUERY_Dx command in the Function parameter and must return either PM_SUCCESS or PM_FAILURE in the Outdata parameter.
Port drivers should return PM_FAILURE in the Outdata in emergency situations only (for example, if entering a system sleep state at this time would definitely result in end-user data loss).
PM_SET_Dx
A PM_SET_Dx command is sent to the port driver when VCOMM receives a CONFIG_APM_SET_Dx message from the Configuration Manager. When a port driver receives this command from VCOMM, it must save or restore device context, prepare the device for subsequent entry into D3 or D0, and return PM_SUCCESS. A port driver cannot return PM_FAILURE for this command.
In response to a PM_SET_D3 message, the port driver must do the following:
1. | Save any device context that will be required to restore the device to D0 |
2. | Perform the actions required to turn off the device (if there are any) |
3. | Return PM_SUCCESS |
In response to a PM_SET_D0 message, the port driver must do the following:
1. | Perform the actions required to turn on the device (if there are any) |
2. | Restore device context |
3. | Return PM_SUCCESS |
Note that in the Windows layered driver architecture, the command that actually causes the device to enter a Dx device state is normally sent by the appropriate bus driver [the Advanced Configuration and Power Interface (ACPI) driver, the Peripheral Component Interconnect (PCI) bus driver, the Universal Serial Bus (USB) class driver, and so on]. VCOMM sends a PM_SET_Dx command to a port driver to give the port driver an additional opportunity to prepare its hardware in advance of the bus driver command.
PM_CANCEL_Dx
A PM_CANCEL_Dx command is sent to the port driver when VCOMM receives a CONFIG_APM_FAILED_Dx message from the Configuration Manager. When a port driver receives a PM_CANCEL_Dx command from VCOMM, that event indicates the system is not going to sleep.
If the port driver has stopped any activity that would prevent the system from going to sleep, as it must do when it returns PM_SUCCESS to a PM_QUERY_Dx command, then the port driver can start such activity again when it receives a PM_CANCEL_Dx command.
PM_ARM_WAKEUP
A PM_ARM_WAKEUP command is sent to the port driver when VCOMM receives a CONFIG_WAKEUP_ARM message from the Configuration Manager. This message is sent only if the operating system, by using bus standard mechanisms, as defined in the ACPI, PCI Power Management, or USB Power Management specifications, determines that the device supports wake-up.
The actual command to enable a device's wake on ring feature is normally made by the appropriate bus driver (the ACPI driver, the PCI bus driver, the USB class driver, and so on). VCOMM sends a PM_ARM_WAKEUP command to a port driver to give the port driver an additional opportunity to prepare its hardware in advance of the bus driver command.
PM_DISARM_WAKEUP
A PM_DISARM_WAKEUP command is sent to the port driver when VCOMM receives a CONFIG_WAKEUP_DISABLE message from the Configuration Manager. This message is sent only if the operating system, by using bus standard mechanisms (as defined in the ACPI, PCI Power Management, or USB Power Management specifications), has determined that the device supports wake-up.
The actual command to disable a device's wake on ring feature is normally made by the appropriate bus driver (the ACPI driver, the PCI bus driver, the USB class driver, and so on). VCOMM sends a PM_DISARM_WAKEUP command to a port driver to give the port driver an additional opportunity to prepare its hardware in advance of the bus driver command.