XXX_PowerDown (Device Manager)

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

This function suspends power to the device. It is useful only with devices that can power down under software control. Such devices are typically, but not exclusively, PC Cards.

Syntax

void XXX_PowerDown(
  DWORD hDeviceContext 
);

Parameters

• hDeviceContext
  [in] Handle to the device context. The call to the XXX_Init (Device Manager) function returns this identifier.

Return Value

None.

Remarks

The power handler functions, XXX_PowerUp (Device Manager) and XXX_PowerDown (Device Manager), execute in kernel mode, and they cannot be pre-empted.

Most function calls are not allowed in this mode. In general, the power handler functions are not allowed to make system calls. The following list shows how the operating system (OS) handles a system call from the XXX_PowerUp function or the XXX_PowerDown function:

1. The OS outputs the following to the kernel debug port.

   ERROR : Power Handler function yield to low priority thread.
   

2. The OS calls the lpNKHaltSystem function.
   By default, lpNKHaltSystem halts the system. You can override this default behavior by initializing lpNKHaltSystem to point to your own function.

You can optionally use DEBUGMSG, RETAILMSG, CeSetPowerOnEvent, and SetInterruptEvent from the power handler functions. For more information about the DEBUGMSG and RETAILMSG macros, see Debugging Macros.

Use the LockPages function to lock in memory all code and data pages accessed by a power handler function. For example, if your device driver executes from RAM that has been paged from NAND flash or decompressed from storage, do not use the DEVFLAGS_LOADLIBRARY flag. This flag allows the code pages of your device driver to be discarded from RAM and paged in as needed. If you are accessing a memory-mapped file, make sure that those data pages have been locked into RAM with the LockPages function.

The power handler functions should never generate an exception. The following list shows some ways that exceptions can be generated:

• Dereferencing a null pointer.
• Dividing by zero. This generates an exception on most microprocessors.
• Explicitly raising an SEH or C++ exception.
• A page-fault.

The following list shows how the OS handles an exception generated from a power handler function.

1. The OS outputs the following string to the kernel debug port.

   !Unrecoverable Error: Exception or calling API inside Power Handler
   

2. The OS calls the lpNKHaltSystem function.
   By default, lpNKHaltSystem halts the system. You can override this default behavior by initializing lpNKHaltSystem to point to your own function.

The OS invokes this function to suspend power to a device. The OS might call this function when it is about to enter a power-save mode. The driver might also receive a separate power-down request from the Power Manager before the XXX_PowerDown function executes. For example, IOCTL_POWER_SET might request a D3 or D4 power state.

Microsoft recommends using Power Manager and the power management IOCTLs to manage power to your device. For more information, see Power Management IOCTLs.

If you do not use Power Manager, this function should only power down the device. XXX_PowerDown should not call any functions that might cause it to block, and it should return as quickly as possible. One strategy for returning quickly is to have XXX_PowerDown set a global variable to indicate that a power loss occurred.

XXX_PowerUp and XXX_PowerDown callbacks can use CeSetPowerOnEvent to signal to arbitrary driver threads that a suspend or resume cycle has occurred. To signal the driver's interrupt service thread, use SetInterruptEvent instead. Device Manager uses the XXX prefix as a placeholder. When implementing the stream interface, replace XXX with a prefix appropriate for your implementation or use undecorated entry point names in conjunction with DEVFLAGS_NAKEDENTRIES. For more information about other valid Flags values, see ActivateDeviceEx.

By default, interrupts are on during stream interface driver entry points.

Requirements

See Also

Reference

ActivateDeviceEx
XXX_Init (Device Manager)
XXX_PowerUp (Device Manager)

Concepts

Device File Names

Other Resources

Controlling Debug Message Output With Macros
Power Management
CeSetPowerOnEvent
IOCTL_POWER_SET
LockPages
lpNKHaltSystem
Power Management I/O Controls
SetInterruptEvent