chapter 6.3: Device Objects

设备对象：
当PnP manager发现一个驱动控制的设备，它会通知framework。framework反过来调用driver来初始化设备数据结构。
device object是驱动对象管理设备的角色，包含状态，是I/O请求的target。而windows不把请求发送给driver。
device包含驱动要使用的device相关信息，支持设备相关事件的回调函数。


DO的类型
1.filter DOs
    filter driver给每个设备创建filter DO，用来修改一至多个设备相关I/O请求。
2.FDOs（functional device objects）
    function driver给每个device创建FDO，用来表示主要驱动的设备。
3.PDOs（physical device objects）
    bus driver为每个连接到bus的设备创建PDP，表示了设备和bus的关系（UMDF无法创建PDO）
4.Control device object
    所有KMDF driver都能创建control device object，表示一个遗留的non-PNP设备或者一个control interface（通过它，PnP接收一个“sideband” I/O request）
    UMDF无法创建该对象
*应该熟悉所有驱动类型和设备对象


Filter Driver和Filter DOs
用来修改或记录request，加密解密，然后就传给栈中下一个对象。
filter driver会告知frameworkdriver类型
filter driver创建queue来保存它过滤的request类型，framework向driver传递这些请求。
还有bus filter driver，为bus执行复杂的、低级的任务。很少用，且WDF不支持。


Function Driver和FDOs
设备的主要驱动，处理I/O，管理设备电源状态。驱动默认创建FDO
KMDF：支持wakesignal，WdfFdoInitXxx和WdfFdoXxx的DDI定义了一组FDO的方法、事件和属性。注册event callbacks，获得physical device的属性。
例子中大多数驱动都创建FDO，但KMDF KbFilter，Toaster Filter和Firefly drivers不创建FDO


Bus Driver和PDO （KMDF）
Bus Driver管理了一个parent device，会枚举一至多个子devices。parent device需要是PCI atapter，USB hub，或可以由用户插入更多设备的设备。
parent device也可以是多功能设备，可以枚举驱动固定的完全不一样的子设备（比如具有音频端口和游戏端口的声卡驱动）
这些设备都被称为“buses”
bus driver的重要区别是它管理了不是devnode末端的节点设备。
bus driver的任务：
    1.处理向bus自己的I/O request
    2.枚举子设备，反馈他们的硬件需求和状态
PnP设备栈中的bus driver通常创建两种device object，自己的FDO和每个子设备的PDO。
PDO相关方法：WdfPdoInitXxx和WdfPdoXxx
driver可以做的事：
    1.注册反馈子设备需要的硬件资源信息回调函数
    2.设备锁和弹出的回调函数
    3.bus-level操作，可以允许子设备发起wake signal的回调函数
    4.给子设备分配PnP，兼容性和实例ID
    5.告知系统子设备已被弹出或意外移除
    6.获得或更新子设备的的bus地址
KMDF在创建DO前通过调用一至多个PDO初始化方法告知这是一个bus driver
       /-------------\
----/raw device\-----
少数情况，bus driver会控制一个raw device，raw device被PDO直接控制，而没有FDO。
bus driver可以表示PDO是“有能力raw”的：比如SCSI，IDE和其他storage bus drivers为连接的设备创建“raw capable”PDO。
对于标准设备，如disc和CD-ROM，系统通过FDO控制设备；若无FDO，则标记它为raw deivce。
storage stack支持“storage pass-through”命令，让client可以直接提出SCSI请求。但不是所有这些bus支持“storage pass-through”
控制raw device的driver被framework认为driver是该设备的power policy manager，但driver可以通过WdfDeviceInitSetPowerPolicyOwner修改设定，但一定要由另一个驱动管理设备的power
--------------------------
        /----------\
-----/枚举模型\------
framework支持枚举设备的动态和静态模型。
static模型适合于多功能设备，只在初始化时枚举。
dynamic模型支持IEEE1394
支持：
    1.向系统汇报子设备
    2.扫描寻找子设备
    3.维护子设备列表
例子：KbFiltr，Osrusbfx2/EnumSwitches，Toaster Bus drivers创建PDOs
-------------------------


Legacy Device Driver和Control Device Objects（KMDF）
不是device stack的一部分。
PnP驱动使用control device object实现独立于device stack的control interface。应用程序直接给它发送请求，而不穿过任何filter driver。
例子：在设备栈但不允许custom IOCTLs的driver会创建一个control device object。
control device object通常有queue，driver可以从queue通过I/O target向PnP device发送request。
驱动必须通过调用WdfControlFinishInitializing告知framework初始化结束。device object必须自己删除control device object。
例子：NdisProt，NonPnP和Toaster Filter创建了control Device object
*SDV annotate


WDF drivers，driver types和device object types
PnP设备通常具有一个function driver和一个bus driver，和任何数量的filter drivers。
对于USB hub，自己有function driver，对每个USB设备有bus driver；在bus driver枚举PDO后，PnP manager会载入每个接入的USB设备的function driver，由function driver创建FDO。
*callback是PDO或FDO相关，而不是function driver相关或bus driver相关。


Device Properties
属性根据从system和bus driver获取的信息生成默认值，但driver创建device时可以修改。

Property	Description	Supporting framework
Alignment requirement	The device's address alignment requirement for memory transfer operations.	KMDF
Default child list	The default child list that the framework creates for an FDO (FDO only).	KMDF, for FDO only
Default I/O queue	The I/O queue that receives the device's I/O requests unless the driver creates additional I/O queues.	UMDF (through INF) and KMDF
Device characteristics	A set of device characteristics that are stored as flags. A driver can set all of these characteristics as a group or can set some characteristics individually.	UMDF; KMDF
Device instance ID	A string that represents the instance ID for the device.	UMDF; KMDF
Device name	Name of the Down device object (UMDF) or of the device object that the driver creates (KMDF). Clients can use the KMDF device object name to open the device, but clients cannot use the UMDF device name.	UMDF; KMDF
Device state	The operational state of a Plug and Play device.	UMDF; KMDF
Filter	A Boolean value that indicates whether the device object represents a filter driver.	UMDF; KMDF
Default I/O target	The next-lower driver in the device stack to which the driver forwards I/O requests.	UMDF; KMDF
Parent	The FDO of the parent bus for an enumerated child device object (PDO only).	KMDF, for PDO only
Plug and Play capabilities	The Plug and Play features of the device, such as locking, surprise removal, and related capabilities.	UMDF; KMDF
Plug and Play state	The current state of the framework's Plug and Play state machine.	KMDF
Power capabilities	The power management features of the device, including the intermediate power states, the states from which it can trigger a wake signal, and related capabilities.	KMDF
Power policy ownership	A Boolean value that indicates whether the device object owns power policy for the device.	UMDF; KMDF
Power policy state	The current state of the framework's power policy state machine.	KMDF
Power state	The current state of the framework's power management state machine.	KMDF
Synchronization model (also called locking constraint)	The level at which the framework calls certain object callbacks concurrently.	UMDF; KMDF

UMDF或KMDF不暴露所有I/O manager给设备保存的属性。UMDF和KMDF可以在framework外获取这些属性。
    UMDF：SetupDiXxx
    KMDF: IoGetDeviceProperty


Device对象初始化
UMDF在IWDFDeviceInitialize接口中提供方法：IDriverEntry::OnDeviceAdd
KMDF提供WdfDeviceIntXxx方法，EvtDriverDeviceAdd回调函数接受从WDFDEVICE_INT结构的由WdfDeviceIntXxx填写指针。
driver在初始化设备前调用设备初始化方法，作为add-device event回调函数的一部分。
初始化设备的PnP能力，设备和其他设备的I/O event callback的并发模型。
KMDF需要比UMDF更多的初始化过程。