// this structure describes a set of power manageable devices

typedef struct _DeviceList_tag {

LPCGUID     pGuid;                  // class of device

PDEVICE_STATE pList;                // pointer to devices

HANDLE      hMsgQ;                  // device notification queue

HANDLE      hnClass;                // handle from RequestDeviceNotifications()

PDEVICE_INTERFACE      pInterface; // interface to the device class power management routines

struct _DeviceList_tag *pNext;      // singly linked list pointer

} DEVICE_LIST, *PDEVICE_LIST;

; Power Manager interfaces.  These list the interface classes that the Power

; Manager will monitor for new devices.

;

[HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Control/Power/Interfaces]

"{A32942B7-920C-486b-B0E6-92A702A99B35}"="Generic power-manageable devices"

"{8DD679CE-8AB4-43c8-A14A-EA4963FAA715}"="Power-manageable block devices"

; @CESYSGEN IF CE_MODULES_NDIS

"{98C5250D-C29A-4985-AE5F-AFE5367E5006}"="Power-manageable NDIS miniports"

; @CESYSGEN ENDIF CE_MODULES_NDIS

; @CESYSGEN IF CE_MODULES_GWES

"{EB91C7C9-8BF6-4a2d-9AB8-69724EED97D1}"="Power-manageable display"

; @CESYSGEN ENDIF CE_MODULES_GWES

// this structure describes a power-manageable device

typedef struct _DeviceState_tag {

LPCTSTR     pszName;                // device's name

CEDEVICE_POWER_STATE    curDx;      // current official power state (not necessarily supported by the device)

CEDEVICE_POWER_STATE    floorDx;    // minimum device power state, or PwrDeviceUnspecified

CEDEVICE_POWER_STATE    ceilingDx;  // maximum device power state, or PwrDeviceUnspecified

CEDEVICE_POWER_STATE    setDx;      // power state if explicitly set, or PwrDeviceUnspecified

CEDEVICE_POWER_STATE    lastReqDx;  // last state requested by the device

CEDEVICE_POWER_STATE    actualDx;   // current actual device power state

CEDEVICE_POWER_STATE    pendingDx;  // Pending DX for updating

DWORD                   dwNumPending; // Number of Pending for updating.

struct _DeviceState_tag *pParent;   // parent device, or NULL

POWER_CAPABILITIES      caps;       // as reported by the device

DWORD       dwRefCount;             // structure can be deallocated when this is 0

HANDLE      hDevice;                // handle to the device from OpenDevice(), or NULL

PDEVICE_INTERFACE       pInterface; // interface to the device class power management routines

struct _DeviceList_tag  *pListHead; // pointer to the containing list

struct _DeviceState_tag *pNext;     // linked list pointers

struct _DeviceState_tag *pPrev;

} DEVICE_STATE, *PDEVICE_STATE;

// this routine determines to which device list a particular device class

// corresponds

PDEVICE_LIST

GetDeviceListFromClass(LPCGUID guidDevClass)

{

PDEVICE_LIST pdl;

SETFNAME(_T("GetDeviceListFromClass"));

PREFAST_DEBUGCHK(guidDevClass != NULL);

// look for a match

__try {

for(pdl = gpDeviceLists; pdl != NULL; pdl = pdl->pNext) {

if(*pdl->pGuid == *guidDevClass) {

break;

}

}

}

__except(EXCEPTION_EXECUTE_HANDLER) {

PMLOGMSG(TRUE, (_T("%s: exception accessing guidDevClass 0x%08x/r/n"),

pszFname, guidDevClass));

pdl = NULL;

}

return pdl;

}

// This routine looks for a device on a list.  If it finds the device, it

// increments its reference counter and returns a pointer to it.  The caller

// should decrement the reference counter when it is done with the pointer.

// Note that the search is case sensitive.

PDEVICE_STATE

DeviceStateFindList(PDEVICE_LIST pdl, LPCTSTR pszName)

{

PDEVICE_STATE pds;

SETFNAME(_T("DeviceStateFindList"));

PMLOCK();

__try {

// look for a match

for(pds = pdl->pList; pds != NULL; pds = pds->pNext) {

if(_tcscmp(pds->pszName, pszName) == 0) {

// increment the reference count and exit

DeviceStateAddRef(pds);

break;

}

}

}

__except(EXCEPTION_EXECUTE_HANDLER) {

PMLOGMSG(ZONE_WARN, (_T("%s: exception searching list/r/n"), pszFname));

pds = NULL;

}

PMUNLOCK();

return pds;

}

typedef struct _DeviceInterface_tag {

BOOL (WINAPI * pfnInitInterface) (VOID);

HANDLE (WINAPI *pfnOpenDevice) (struct _DeviceState_tag *);

BOOL (WINAPI * pfnCloseDevice) (HANDLE);

BOOL (WINAPI * pfnRequestDevice) (HANDLE, DWORD, LPVOID, DWORD, LPVOID, DWORD, LPDWORD);

} DEVICE_INTERFACE, *PDEVICE_INTERFACE;

// This routine reads the registry to determine what type of device interfaces

// we will be monitoring.  The default PM GUID is ignored if present in the

// registry and is always added last (so it's first in the list).

BOOL

DeviceListsInit(VOID)

{

BOOL fOk = TRUE;

PDEVICE_LIST pdl;

DWORD dwStatus;

HKEY hk;

TCHAR szBuf[MAX_PATH];

SETFNAME(_T("DeviceListsInit"));

// enumerate all the device classes

// 到注册表[HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Control/Power/Interfaces]下

// 获取GUID的值，默认情况下，ICLASS共有类别，此处直接通过枚举的方式查询到每一个GUID

wsprintf(szBuf, _T("%s//Interfaces"), PWRMGR_REG_KEY);

dwStatus = RegOpenKeyEx(HKEY_LOCAL_MACHINE, szBuf, 0, 0, &hk);

if(dwStatus == ERROR_SUCCESS) {

DWORD dwIndex = 0;

do {

DWORD cbValueName = dim(szBuf), dwType;

GUID idInterface;

dwStatus = RegEnumValue(hk, dwIndex, szBuf, &cbValueName, NULL,

&dwType, NULL, NULL);

if(dwStatus == ERROR_SUCCESS) {

if(dwType != REG_SZ) {

PMLOGMSG(ZONE_WARN, (_T("%s: invalid type for value '%s'/r/n"),

pszFname, szBuf));

}

// 将GUID进行转换

else if(!ConvertStringToGuid(szBuf, &idInterface)) {

PMLOGMSG(ZONE_WARN, (_T("%s: can't convert '%s' to GUID/r/n"),

pszFname, szBuf));

}

// 如果是通用设备的GUID，则跳过，留到最后进行初始化其DEVICE_LIST

else if(idInterface == idGenericPMDeviceClass) {

PMLOGMSG(ZONE_INIT, (_T("%s: default GUID found in registry as expected/r/n"),

pszFname));

}

// 为特定GUID类分配并初始化一个DEVICE_LIST结构体变量

else if((pdl = DeviceListCreate(&idInterface)) == NULL) {

PMLOGMSG(ZONE_WARN, (_T("%s: DeviceListCreate() failed/r/n"),

pszFname));

}

// 初始化上面分配的DEVICE_LIST结构体变量的成员pInterface，使其指向有效的函数指针结构体

// 函数PlatformDeviceListInit这里非常重要，它初始化了DEVICE_LIST结构体变量的成员pInterface，而pInterface的具体实现包括gDisplayInterface和gStreamInterface，在pmstream.cpp和pmdisplay.cpp可以找到其具体的实现，代码写的蛮经典的

// 这些函数指针结构体通过PM Driver的MDD层获得

else if(PlatformDeviceListInit(pdl) == FALSE) {

PMLOGMSG(ZONE_WARN, (_T("%s: PlatformDeviceListInit() failed/r/n"),

pszFname));

DeviceListDestroy(pdl);

}

// 将当前GUID的DEVICE_LIST结构体变量添加链表gpDeviceLists中

else {

// add the new entry to the list

pdl->pNext = gpDeviceLists;

gpDeviceLists = pdl;

}

// update the index

dwIndex++;

}

} while(dwStatus == ERROR_SUCCESS);

// check for abnormal termination of the loop

if(dwStatus != ERROR_NO_MORE_ITEMS) {

fOk = FALSE;

}

// close the registry handle

RegCloseKey(hk);

}

// add the default list last

// 通用设备类留在最后进行初始化，为什么？

// 主要是为了让通用设备类保持在gpDeviceLists的最前面，利于后面的处理

if(fOk) {

fOk = FALSE;

pdl = DeviceListCreate(&idGenericPMDeviceClass);

if(pdl != NULL) {

if(PlatformDeviceListInit(pdl) == FALSE) {

PMLOGMSG(ZONE_INIT || ZONE_WARN,

(_T("%s: PlatformDeviceListInit() failed for default class/r/n"),

pszFname));

DeviceListDestroy(pdl);

} else {

pdl->pNext = gpDeviceLists;

gpDeviceLists = pdl;

fOk = TRUE;

}

}

}

// clean up if necessary

if(!fOk) {

PMLOGMSG(ZONE_WARN, (_T("%s: error during list initialization/r/n"),

pszFname));

while(gpDeviceLists != NULL) {

pdl = gpDeviceLists;

gpDeviceLists = pdl->pNext;

pdl->pNext = NULL;

DeviceListDestroy(pdl);

}

}

return fOk;

}

// this thread waits for power manageable devices to be announced.  When

// they arrive they are added to the PM's list of devices and initialized

// appropriately.  If a device goes away, its entry will be removed

// from the list.

DWORD WINAPI

PnpThreadProc(LPVOID lpvParam)

{

DWORD dwStatus;

HANDLE hnGeneric = NULL;

HANDLE hevReady = (HANDLE) lpvParam;

HANDLE hEvents[MAXIMUM_WAIT_OBJECTS];

DWORD dwNumEvents = 0;

BOOL fDone = FALSE;

BOOL fOk;

INT iPriority;

PDEVICE_LIST pdl;

SETFNAME(_T("PnpThreadProc"));

PMLOGMSG(ZONE_INIT, (_T("+%s: thread 0x%08x/r/n"), pszFname, GetCurrentThreadId()));

// set the thread priority

if(!GetPMThreadPriority(_T("PnPPriority256"), &iPriority)) {

iPriority = DEF_PNP_THREAD_PRIORITY;

}

CeSetThreadPriority(GetCurrentThread(), iPriority);

// first list entry is the exit event

hEvents[dwNumEvents++] = ghevPmShutdown;

// set up device notifications

for(pdl = gpDeviceLists; pdl != NULL && dwNumEvents < dim(hEvents); pdl = pdl->pNext) {

hEvents[dwNumEvents++] = pdl->hMsgQ;

// 有几个GUID类别，就申请几个通知

pdl->hnClass = RequestDeviceNotifications(pdl->pGuid, pdl->hMsgQ, TRUE);

if(pdl->hnClass == NULL) {

PMLOGMSG(ZONE_WARN, (_T("%s: RequestDeviceNotifications() failed %d/r/n"),

pszFname, GetLastError()));

}

}

DEBUGCHK(dwNumEvents > 1);

// we're up and running

SetEvent(hevReady);

// wait for new devices to arrive

while(!fDone) {

dwStatus = WaitForMultipleObjects(dwNumEvents, hEvents, FALSE, INFINITE);

if(dwStatus == (WAIT_OBJECT_0 + 0)) {

PMLOGMSG(ZONE_WARN, (_T("%s: shutdown event set/r/n"), pszFname));

fDone = TRUE;

} else if(dwStatus > WAIT_OBJECT_0 && dwStatus <= (WAIT_OBJECT_0 + MAXIMUM_WAIT_OBJECTS)) {

dwStatus -= WAIT_OBJECT_0;

// 收到通知就就对特定GUID设备的电源状态进行获取

fOk = ProcessPnPMsgQueue(hEvents[dwStatus]);

if(!fOk) {

PMLOGMSG(ZONE_WARN, (_T("%s: ProcessPnPMsgQueue(0x%08x) failed/r/n"), pszFname,

hEvents[dwStatus]));

}

} else {

PMLOGMSG(ZONE_WARN, (_T("%s: WaitForMultipleObjects() returned %d, status is %d/r/n"),

pszFname, dwStatus, GetLastError()));

fDone = TRUE;

break;

}

}

// release resources

for(pdl = gpDeviceLists; pdl != NULL; pdl = pdl->pNext) {

if(pdl->hnClass != NULL) StopDeviceNotifications(pdl->hnClass);

}

// all done

PMLOGMSG(ZONE_INIT | ZONE_WARN, (_T("-%s: exiting/r/n"), pszFname));

return 0;

}

// This routine adds a device to the list associated with its device class.

// This routine does not return a value; it will either create a new

// device state structure and add it to a list or it will not.  If the new

// device duplicates an existing one this routine won't create a new node.

// This routine executes in the context of the PnP thread, which handles

// device interface additions and removals.

VOID

AddDevice(LPCGUID guidDevClass, LPCTSTR pszName, PDEVICE_STATE pdsParent,

PPOWER_CAPABILITIES pCaps)

{

SETFNAME(_T("AddDevice"));

PMLOGMSG(ZONE_DEVICE,

(_T("%s: adding '%s', pdsParent 0x%08x, pCaps 0x%08x to class %08x-%04x-%04x-%04x-%02x%02x%02x%02x%02x%02x/r/n"),

pszFname, pszName, pdsParent, pCaps,

guidDevClass->Data1, guidDevClass->Data2, guidDevClass->Data3,

(guidDevClass->Data4[0] << 8) + guidDevClass->Data4[1], guidDevClass->Data4[2], guidDevClass->Data4[3],

guidDevClass->Data4[4], guidDevClass->Data4[5], guidDevClass->Data4[6], guidDevClass->Data4[7]));

// figure out onto which list this device should be added

// 到DEVICE_LIST链表中查询当前设备所在的GUID类对应的DEVICE_LIST指针

PDEVICE_LIST pdl = GetDeviceListFromClass(guidDevClass);

// did we find the list?

if(pdl != NULL) {

// check for duplicates

// 到当前设备所对应的DEVICE_LIST链表中查询是否在名字为pszName的设备

PDEVICE_STATE pds = DeviceStateFindList(pdl, pszName);

// create the device if it doesn't already exist

// 如果不存在，则创建一个

if(pds == NULL) {

BOOL fOk = FALSE;

// 为当前设备创建一个DEVICE_STATE节点

pds = DeviceStateCreate(pszName);

if(pds != NULL) {

// if we are passed the device's capabilities, just copy them

// into the structure

if(pCaps != NULL) {

__try {

pds->caps = *pCaps;

}

__except(EXCEPTION_EXECUTE_HANDLER) {

PMLOGMSG(ZONE_WARN,

(_T("%s: exception during capabilities copy from 0x%08x/r/n"),

pszFname, pCaps));

pCaps = NULL;

}

}

// update the device's parent pointer

if(pdsParent != NULL) {

DeviceStateAddRef(pdsParent);

}

pds->pParent = pdsParent;

// add the new device to its class list

// 将当前设备的DEVICE_STATE加入到guidDevClass对应的DEVICE_LIST链表中

if(!DeviceStateAddList(pdl, pds)) {

// deallocate the node, reference count isn't incremented

DeviceStateDecRef(pds);

pds = NULL;

} else {

PREFAST_DEBUGCHK(pds->pInterface != NULL);

PREFAST_DEBUGCHK(pds->pInterface->pfnOpenDevice != NULL);

PREFAST_DEBUGCHK(pds->pInterface->pfnRequestDevice != NULL);

PREFAST_DEBUGCHK(pds->pInterface->pfnCloseDevice != NULL);

// 获取设备的操作Handle，这里比较重要，调用的其实是MDD层中首先的函数OpenStreamDevice或者OpenDisplayDevice

pds->hDevice = pds->pInterface->pfnOpenDevice(pds);

if(pds->hDevice == INVALID_HANDLE_VALUE) {

PMLOGMSG(ZONE_WARN, (_T("%s: couldn't open device '%s'/r/n"),

pszFname, pszName != NULL ? _T("<NULL>") : pszName));

} else {

// do we need to request capabilities?

fOk = TRUE;             // assume success

if(pCaps == NULL) {

DWORD dwBytesReturned;

POWER_RELATIONSHIP pr;

PPOWER_RELATIONSHIP ppr = NULL;

memset(&pr, 0, sizeof(pr));

if(pds->pParent != NULL) {

PMLOGMSG(ZONE_DEVICE, (_T("%s: parent of '%s' is '%s'/r/n"),

pszFname, pds->pszName, pds->pParent->pszName));

pr.hParent = (HANDLE) pds->pParent;

pr.pwsParent = pds->pParent->pszName;

pr.hChild = (HANDLE) pds;

pr.pwsChild = pds->pszName;

ppr = &pr;

}

// get the device's capabilities structure

// 有点意思了，呵呵，调用IOCTL_POWER_CAPABILITIES获取设备所支持的电源状态这里比较重要，调用的其实是MDD层中首先的函数RequestStreamDevice或者RequestDisplayDevice，对于这两类设备来说，分别调用到设备驱动中的DeviceIoControl和ExtEscape

fOk = pds->pInterface->pfnRequestDevice(pds->hDevice, IOCTL_POWER_CAPABILITIES,

ppr, ppr == NULL ? 0 : sizeof(*ppr),

&pds->caps, sizeof(pds->caps), &dwBytesReturned);

// sanity check the size in case a device is just returning

// a good status on all ioctls for some reason

if(fOk && dwBytesReturned != sizeof(pds->caps)) {

PMLOGMSG(ZONE_WARN,

(_T("%s: invalid size returned from IOCTL_POWER_CAPABILITIES/r/n"),

pszFname));

fOk = FALSE;

}

}

// any problems so far?

if(fOk) {

// determine whether we should request power relationships from a parent device

// 帮助文档中提到，这里的意思是：

// Set to POWER_CAP_PARENT bit if the device would like to receive an IOCTL_REGISTER_POWER_RELATIONSHIP call after initialization

// BSP中并没有使用，应该不用关注

if((pds->caps.Flags & POWER_CAP_PARENT) != 0) {

pds->pInterface->pfnRequestDevice(pds->hDevice, IOCTL_REGISTER_POWER_RELATIONSHIP,

NULL, 0, NULL, 0, NULL);

}

}

}

}

// have we read all the configuration information we need from

// the new device

if(!fOk) {

// no, delete the device

DeviceStateRemList(pds);

} else {

// See if the device supports multiple handles.  Power manageable devices

// should allow multiple open handles, but if they don't we will have to open

// one before each access.

HANDLE hDevice = pds->pInterface->pfnOpenDevice(pds);

if(hDevice == INVALID_HANDLE_VALUE) {

PMLOGMSG(ZONE_WARN, (_T("%s: WARNING: '%s' does not support multiple handles/r/n"),

pszFname));

pds->pInterface->pfnCloseDevice(pds->hDevice);

pds->hDevice = INVALID_HANDLE_VALUE;

} else {

// close the second handle, since we don't need it

pds->pInterface->pfnCloseDevice(hDevice);

}

// initialize the new device's power state variables

// 这里就不用说了，更新电源状态，呵呵

UpdateDeviceState(pds);

}

}

}

// we are done with the device pointer

if(pds != NULL) {

DeviceStateDecRef(pds);

}

} else {

PMLOGMSG(ZONE_WARN, (_T("%s: class for device '%s' not supported/r/n"),

pszFname, pszName));

}

}

Beginning with Windows CE .NET 4.10, power-manageable devices can belong to varying device classes. These device classes consist both of predefined classes as well as custom device classes. The Power Manager APIs that accept device names can also accept class-qualified device names. For example, each of the following names is a valid device name:

·                 COM1:

·                 {A32942B7-920C-486b-B0E6-92A702A99B35}/COM1:

·                 {98C5250D-C29A-4985-AE5F-AFE5367E5006}/CISCO1

·                 {8DD679CE-8AB4-43c8-A14A-EA4963FAA715}/DSK1:

If a class does not qualify a device name, the device is assumed to belong to the default device class. For example, the names COM1: and {A32942B7-920C-486b-B0E6-92A702A99B35}/COM1: are equivalent.