configmg.h

来自「用于查询PC机上的USB端口是否有设备挂接上」· C头文件 代码 · 共 1,777 行 · 第 1/5 页

 * 
 *	Each devnode has a config handler field and a enum handler field
 *	which are getting called every time Configuration Manager wants a
 *	devnode to perform some configuration related function. The handler
 *	is registered with CM_Register_Device_Driver or
 *	CM_Register_Enumerator, depending if the handler is for the device
 *	itself or for one of the children of the devnode.
 *
 *	The registered handler is called with:
 *
 *	result=dnToDevNode->dn_Config(if dnToDevNode==dnAboutDevNode)
 *	result=dnToDevNode->dn_Enum(if dnToDevNode!=dnAboutDevNode)
 *					(	FuncName,
 *					 	SubFuncName,
 *						dnToDevNode,
 *						dnAboutDevNode, (if enum)
 *						dwRefData, (if driver)
 *						ulFlags);
 *	Where:
 *
 *	FuncName is one of CONFIG_FILTER, CONFIG_START, CONFIG_STOP,
 *	CONFIG_TEST, CONFIG_REMOVE, CONFIG_ENUMERATE, CONFIG_SETUP or
 *	CONFIG_CALLBACK.
 *
 *	SubFuncName is the specific CONFIG_xxxx_* that further describe
 *	we START, STOP or TEST.
 *
 *	dnToDevNode is the devnode we are calling. This is given so that
 *	a signle handler can handle multiple devnodes.
 *
 *	dnAboutDevNode specifies which devnode the function is about. For
 *	a config handler, this is necessarily the same as dnToDevNode. For
 *	an enumerator handler, this devnode is necessarily different as it
 *	is a child of the dnToDevNode (special case: CONFIG_ENUMERATE
 *	necessarily has dnAboutDevNode==NULL). For instance, when starting
 *	a COM devnode under a BIOS enumerator, we would make the following
 *	two calls:
 *
 *		To BIOS with (CONFIG_START, ?, BIOS, COM, ?, 0).
 *
 *		To COM with (CONFIG_START, ?, COM, COM, ?, 0).
 *
 *	dwRefData is a dword of reference data. For a config handler, it is
 *	the DWORD passed on the CONFIGMG_Register_Device_Driver call. For an
 *	enumerator, it is the same as CONFIGMG_Get_Private_DWord(?,
 *	dnToDevNode, dnToDevNode, 0).
 *
 *	ulFlags is 0 and is reserved for future extensions.
 *
 *	Here is the explanation of each event, in parenthesis I put the
 *	order the devnodes will be called:
 *
 *	CONFIG_FILTER (BRANCH GOING UP) is the first thing called when a new
 *	insertion or change of configuration need to be processed. First
 *	CM copies the requirement list (BASIC_LOG_CONF) onto the filtered
 *	requirement list (FILTER_LOG_CONF) so that they are originally
 *	the same. CM then calls every node up, giving them the chance to
 *	patch the requirement of the dnAboutDevNode (they can also
 *	alter their own requirement). Examples are PCMCIA which would
 *	remove some IRQ that the adapter can't do, prealloc some IO
 *	windows and memory windows. ISA which would limit address space
 *	to being <16Meg. A device driver should look only at
 *	FILTER_LOG_CONF during this call.
 *
 *	CONFIG_START (BRANCH GOING DOWN) are called to change the
 *	configuration. A config handler/enumerator hander should look
 *	only at the allocated list (ALLOC_LOG_CONF).
 *
 *	CONFIG_STOP (WHOLE TREE BUT ONLY DEVNODES THAT CHANGE
 *	CONFIGURATION (FOR EACH DEVNODE, BRANCH GOING UP)) is called
 *	for two reasons:
 *
 *		1) Just after the rebalance algorithm came up with a
 *		solution and we want to stop all devnodes that will be
 *		rebalance. This is to avoid the problem of having two cards
 *		that can respond to 110h and 220h and that need to toggle
 *		their usage. We do not want two people responding to 220h,
 *		even for a brief amount of time. This is the normal call
 *		though.
 *
 *		2) There was a conflict and the user selected this device
 *		to kill.
 *
 *	CONFIG_TEST (WHOLE TREE) is called before starting the rebalance
 *	algorithm. Device drivers that fail this call will be considered
 *	worst than jumpered configured for the reminder of this balancing
 *	process. 
 *
 *	CONFIG_REMOVE (FOR EACH SUB TREE NODE, DOING BRANCH GOING UP), is
 *	called when someone notify CM via CM_Remove_SubTree that a devnode
 *	is not needed anymore. A static VxD probably has nothing to do. A
 *	dynamic VxD should check whether it should unload itself (return
 *	CR_SUCCESS_UNLOAD) or not (CR_SUCCESS).
 *
 *	Note, failing any of CONFIG_START, or CONFIG_STOP is really bad,
 *	both in terms of performance and stability. Requirements for a
 *	configuration to succeed should be noted/preallocated during
 *	CONFIG_FILTER. Failing CONFIG_TEST is less bad as what basically
 *	happens is that the devnode is considered worst than jumpered
 *	configured for the reminder of this pass of the balancing algorithm.
 *
 *	COMFIG_ENUMERATE, the called node should create children devnodes
 *	using CM_Create_DevNode (but no need for grand children) and remove
 *	children using CM_Remove_SubTree as appropriate. Config Manager
 *	will recurse calling the children until nothing new appears. During
 *	this call, dnAboutDevNode will be NULL. Note that there is an easy
 *	way for buses which do not have direct children accessibility to
 *	detect (ISAPNP for instance will isolate one board at a time and
 *	there is no way to tell one specific board not to participate in
 *	the isolation sequence):
 *
 *	If some children have soft-eject capability, check those first.
 *	If the user is pressing the eject button, call Query_Remove_SubTree
 *	and if that succeed, call Remove_SubTree.
 *
 *	Do a CM_Reset_Children_Marks on the bus devnode.
 *
 *	Do the usual sequence doing CM_Create_DevNode calls. If a devnode
 *	was already there, CR_ALREADY_SUCH_DEVNODE is returned and this
 *	devnode's DN_HAS_MARK will be set. There is nothing more to do with
 *	this devnode has it should just continue running. If the devnode
 *	was not previously there, CR_SUCCESS will be return, in which case
 *	the enumerator should add the logical configurations.
 *
 *	Once all the devnode got created. The enumerator can call
 *	CM_Remove_Unmarked_Children to remove the devnode that are now gone.
 *	Essentially, this is a for loop thru all the children of the bus
 *	devnode, doing Remove_SubTree on the the devnode which have their
 *	mark cleared. Alternatively, an enumerator can use CM_Get_Child,
 *	CM_Get_Sibling, CM_Remove_SubTree and CM_Get_DevNode_Status.
 *
 *	For CONFIG_SETUP, the called node should install drivers if it
 *	know out to get them. This is mostly for drivers imbeded in the
 *	cards (ISA_RTR, PCI or PCMCIA). For most old cards/driver, this
 *	should return CR_NO_DRIVER.
 *
 *	WARNING: For any non-defined service, the enumertor / device
 *	driver handler should return CR_DEFAULT. This will be treated
 *	as the compatibility case in future version.
 *
 *	So normally what happens is as follows:
 *
 *	- Some detection code realize there is a new device. This can be at
 *	initialization time or at run-time (usually during a media_change
 *	interrupt). The code does a CM_Reenumerate_DevNode(dnBusDevNode)
 *	asynchronous call.
 *
 *	- During appy time event, CM gets notified.
 *
 *	- CM calls the enumerator with:
 *
 *		BusEnumHandler(CONFIG_ENUMERATE, 0, dnBusDevNode, NULL, ?, 0);
 *
 *	- The parent uses CM_Create_DevNode and CM_Remove_SubTree as
 *	appropriate, usually for only its immediate children.
 *
 *	- The parent return to CM from the enumerator call.
 *
 *	- CM walks the children, first loading their device driver if
 *	needed, then calling their enumerators. Thus the whole process
 *	will terminate only when all grand-...-grand-children have stopped
 *	using CM_Create_DevNode.
 *
 *	If rebalance is called (a new devnode is conflicting):
 *
 *	- All devnode receives the CONFIG_TEST. Devnodes that
 *	fail it are considered worst than jumpered configured.
 *
 *	- CM does the rebalance algorithm.
 *
 *	- All affected devnodes that where previously loaded get the
 *	CONFIG_STOP event.
 *
 *	- All affected devnode and the new devnodes receives a CONFIG_START.
 *
 *	If rebalancing failed (couldn't make one or more devnodes work):
 *
 *	- Device installer is called which will present the user with a
 *	choice of devnode to kill.
 *
 *	- Those devnodes will received a CONFIG_STOP message.
 *
 *	WARNING: Don't get confused by:
 *
 *	CONFIG_LOCK/UNLOCK and the NEEDS_LOCKING property are used to mean
 *	locking down the memory used by this driver that needs special
 *	interrupts off processing during suspend (namely the paging device,
 *	the PCI IRQ holders or an ACPI region provider). No OEM drivers
 *	should require this processing.
 *
 *			versus
 *
 *	CONFIG_EJECT_LOCK/UNLOCK and the LOCK_CAPABLE property which means
 *	that the device can be dynamically locked/unlocked for ejection.
 *	NTKERN/ACPI will typically process locking, until cardbus or some
 *	other non-WDM bus support it.
 *	
 ***************************************************************************/

// Possible CONFIGFUNC FuncNames:

#define	CONFIG_FILTER		0x00000000	// Ancestors must filter requirements.
#define	CONFIG_START		0x00000001	// Devnode dynamic initialization.
#define	CONFIG_STOP		0x00000002	// Devnode must stop using config.
#define	CONFIG_TEST		0x00000003	// Can devnode change state now.
#define	CONFIG_REMOVE		0x00000004	// Devnode must stop using config.
#define	CONFIG_ENUMERATE	0x00000005	// Devnode must enumerated.
#define	CONFIG_SETUP		0x00000006	// Devnode should download driver.
#define	CONFIG_CALLBACK		0x00000007	// Devnode is being called back.
#define	CONFIG_APM		0x00000008	// APM functions.
#define	CONFIG_TEST_FAILED	0x00000009	// Continue as before after a TEST.
#define	CONFIG_TEST_SUCCEEDED	0x0000000A	// Prepare for the STOP/REMOVE.
#define	CONFIG_VERIFY_DEVICE	0x0000000B	// Insure the legacy card is there.
#define	CONFIG_PREREMOVE	0x0000000C	// Devnode must stop using config.
#define	CONFIG_SHUTDOWN		0x0000000D	// We are shutting down.
#define	CONFIG_PREREMOVE2	0x0000000E	// Devnode must stop using config.
#define	CONFIG_READY		0x0000000F	// The devnode has been setup.
#define	CONFIG_PROP_CHANGE	0x00000010	// The property page is exiting.
#define	CONFIG_PRIVATE		0x00000011	// Someone called Call_Handler.
#define	CONFIG_PRESHUTDOWN	0x00000012	// We are shutting down
#define	CONFIG_BEGIN_PNP_MODE	0x00000013	// We will start configuring PNP devs.
#define	CONFIG_LOCK		0x00000014	// Gets call during suspend
#define	CONFIG_UNLOCK		0x00000015	// Gets call during resume
#define CONFIG_IRP		0x00000016	// IRP from WDM driver
#define	CONFIG_WAKEUP		0x00000017	// Please arm/disarm the wake up.
#define	CONFIG_WAKEUP_CALLBACK	0x00000018	// You are waking up
#define	CONFIG_EJECT_LOCK	0x00000019	// Device lock
#define	CONFIG_EJECT_UNLOCK	0x0000001A	// Device unlock
#define	NUM_CONFIG_COMMANDS	0x0000001B	// For DEBUG

/*XLATOFF*/

#define	DEBUG_CONFIG_NAMES \
char	CMFAR *lpszConfigName[NUM_CONFIG_COMMANDS]= \
{ \
	"CONFIG_FILTER", \
	"CONFIG_START", \
	"CONFIG_STOP", \
	"CONFIG_TEST", \
	"CONFIG_REMOVE", \
	"CONFIG_ENUMERATE", \
	"CONFIG_SETUP", \
	"CONFIG_CALLBACK", \
	"CONFIG_APM", \
	"CONFIG_TEST_FAILED", \
	"CONFIG_TEST_SUCCEEDED", \
	"CONFIG_VERIFY_DEVICE", \
	"CONFIG_PREREMOVE", \
	"CONFIG_SHUTDOWN", \
	"CONFIG_PREREMOVE2", \
	"CONFIG_READY", \
	"CONFIG_PROP_CHANGE", \
	"CONFIG_PRIVATE", \
	"CONFIG_PRESHUTDOWN", \
	"CONFIG_BEGIN_PNP_MODE", \
	"CONFIG_LOCK", \
	"CONFIG_UNLOCK", \
	"CONFIG_IRP", \
	"CONFIG_WAKE", \
	"CONFIG_WAKE_CB", \
	"CONFIG_EJ_LOCK", \
	"CONFIG_EJ_UNLOCK", \
};

/*XLATON*/

// Possible SUBCONFIGFUNC SubFuncNames:

#define	CONFIG_START_DYNAMIC_START			0x00000000
#define	CONFIG_START_FIRST_START			0x00000001
#define	CONFIG_START_SHUTDOWN_START			0x00000002

#define NUM_START_COMMANDS				0x00000003

/*XLATOFF*/

#define DEBUG_START_NAMES \
char	CMFAR *lpszStartName[NUM_START_COMMANDS] = \
{ \
    	"DYNAMIC_START", \
	"FIRST_START", \
	"SHUTDOWN_START", \
};

/*XLATON*/

#define	CONFIG_STOP_DYNAMIC_STOP			0x00000000
#define	CONFIG_STOP_HAS_PROBLEM				0x00000001
#define	CONFIG_STOP_HIBERNATE_RESET			0x00000002

#define NUM_STOP_COMMANDS				0x00000003

/*XLATOFF*/

#define DEBUG_STOP_NAMES \
char	CMFAR *lpszStopName[NUM_STOP_COMMANDS] = \
{ \
    	"DYNAMIC_STOP", \
	"HAS_PROBLEM", \
	"HIBERNATE_RESET", \
};

/*XLATON*/

//
// For both CONFIG_REMOVE, CONFIG_PREREMOVE and CONFIG_POSTREMOVE
//
#define	CONFIG_REMOVE_DYNAMIC				0x00000000
#define	CONFIG_REMOVE_SHUTDOWN				0x00000001
#define	CONFIG_REMOVE_REBOOT				0x00000002

#define	CONFIG_SHUTDOWN_OFF				0x00000000
#define	CONFIG_SHUTDOWN_REBOOT				0x00000001

#define NUM_REMOVE_COMMANDS				0x00000003

/*XLATOFF*/

#define DEBUG_REMOVE_NAMES \
char	CMFAR *lpszRemoveName[NUM_REMOVE_COMMANDS] = \
{ \
    	"DYNAMIC", \
	"SHUTDOWN", \
	"REBOOT", \
};

/*XLATON*/

#define	CONFIG_ENUMERATE_DYNAMIC			0x00000000
#define	CONFIG_ENUMERATE_FIRST_TIME			0x00000001

#define NUM_ENUMERATE_COMMANDS				0x00000002

/*XLATOFF*/

#define DEBUG_ENUMERATE_NAMES \
char	CMFAR *lpszEnumerateName[NUM_ENUMERATE_COMMANDS] = \
{ \
    	"DYNAMIC", \
	"FIRST_TIME", \
};

/*XLATON*/

#define	CONFIG_TEST_CAN_STOP				0x00000000
#define	CONFIG_TEST_CAN_REMOVE				0x00000001

#define NUM_TEST_COMMANDS				0x00000002

/*XLATOFF*/

#define DEBUG_TEST_NAMES \
char	CMFAR *lpszTestName[NUM_TEST_