使用自动同步
基于框架的驱动程序中几乎所有的代码都驻留在事件回调函数中。 框架会自动同步驱动程序的大部分回调函数,如下所示:
- 框架始终将 常规设备对象、 功能设备对象 (FDO) 和 物理设备对象 (PDO) 事件回调函数同步,以便每个设备一次只能调用 除 EvtDeviceSurpriseRemoval、 EvtDeviceQueryRemove 和 EvtDeviceQueryStop以外的一个回调 函数。 这些回调函数支持即插即用 PnP和电源管理事件,并在 IRQL = PASSIVE_LEVEL 调用;
- (可选)框架可以同步处理驱动程序 I/O 请求的回调函数的执行,以便这些回调函数一次运行一个。 具体而言,框架可以同步 队列、 中断、 延迟过程调用 (DPC) 、 计时器、 工作项和 文件 对象的回调函数,以及请求对象的 EvtRequestCancel 回调函数。 框架在 IRQL = DISPATCH_LEVEL 调用其中大多数回调函数,但你可以强制队列和文件对象回调函数在 IRQL = PASSIVE_LEVEL 运行。 工作项回调函数始终在 PASSIVE_LEVEL运行;
框架使用一组内部同步锁实现此自动同步。 框架确保两个或多个线程不能同时调用同一回调函数,因为每个线程必须等到可以获取同步锁后再调用回调函数。
驱动程序应将特定于对象的数据存储在 对象上下文空间中。 如果驱动程序仅使用框架定义的接口,则只有接收对象句柄的回调函数才能访问此数据。 如果框架正在同步对驱动程序回调函数的调用,则一次只会调用一个回调函数,并且一次只能访问一个回调函数的对象的上下文空间。
除非驱动程序实现 被动级中断处理,否则服务中断和访问中断数据的代码必须在设备的 IRQL (DIRQL) 上运行,并且需要额外的同步。
如果驱动程序启用处理 I/O 请求的回调函数的自动同步,框架将同步这些回调函数,以便一次运行一个回调函数。 下表列出了框架同步的回调函数。
(可选)框架还可以将这些回调函数与驱动程序为设备提供的任何中断、DPC、工作项和计时器对象回调函数同步, 不包括中断对象的 EvtInterruptIsr 回调函数。 若要启用此附加同步,驱动程序必须将这些对象的配置结构的 AutomaticSerialization 成员设置为 TRUE。
总之,框架的自动同步功能提供以下功能:
- 框架始终同步每个设备的 PnP 和电源管理回调函数;
- (可选)框架可以同步 I/O 队列的请求处理程序和一些附加回调函数 (查看上表) ;
- 驱动程序可以要求框架同步中断、DPC、工作项和计时器对象的回调函数;
- 驱动程序必须使用同步中断代码中所述的技术来同步服务中断和访问 中断数据的代码;
- 框架不会同步驱动程序的其他回调函数,例如驱动程序的 CompletionRoutine 回调函数或 I/O 目标对象定义的回调函数。 相反,框架提供了驱动程序可用于同步这些回调函数的其他 锁 ;
选择同步范围
可以选择让框架同步与设备的所有 I/O 队列关联的所有回调函数。 或者,可以选择让框架单独同步每个设备的 I/O 队列的回调函数。 驱动程序可用的同步选项如下所示:
- 设备级同步:框架为设备的所有 I/O 队列同步上表包含的回调函数,以便它们一次运行一个。 框架通过在调用回调函数之前获取设备的同步锁来实现此同步;
- 队列级同步:框架为每个单独的 I/O 队列同步上表包含的回调函数,以便它们一次运行一个。 框架通过在调用回调函数之前获取队列的同步锁来实现此同步;
- 无同步
框架不会同步上表包含的回调函数的执行,并且不会在调用回调函数之前获取同步锁。 如果需要同步,驱动程序必须提供同步。
若要指定是希望框架为驱动程序提供设备级同步、队列级同步还是不同步,可以为驱动程序对象、设备对象或队列对象指定 同步范围 。 对象的WDF_OBJECT_ATTRIBUTES结构的 SynchronizationScope 成员标识对象的同步范围。 驱动程序可以指定的同步范围值包括:
- WdfSynchronizationScopeDevice:框架通过获取设备对象的同步锁进行同步;
- WdfSynchronizationScopeQueue:框架通过获取队列对象的同步锁进行同步;
- WdfSynchronizationScopeNone:框架不会同步,也不会获取同步锁;
- WdfSynchronizationScopeInheritFromParent:框架从对象的父对象获取对象的 SynchronizationScope 值;
通常,不建议使用设备级同步。
驱动程序对象的默认同步作用域为 WdfSynchronizationScopeNone。 设备和队列对象的默认同步作用域为 WdfSynchronizationScopeInheritFromParent。
如果希望框架为所有设备提供设备级同步,可以使用以下步骤:
在驱动程序的驱动程序对象的WDF_OBJECT_ATTRIBUTES结构中,将 SynchronizationScope 设置为 WdfSynchronizationScopeDevice。
为每个设备对象使用默认的 WdfSynchronizationScopeInheritFromParent 值。
或者,若要为单个设备提供设备级同步,可以使用以下步骤:
1. 对驱动程序对象使用默认的 WdfSynchronizationScopeNone 值。
2. 在单个设备对象的WDF_OBJECT_ATTRIBUTES结构中,将 SynchronizationScope 设置为 WdfSynchronizationScopeDevice。
如果希望框架为设备提供队列级同步,可以使用以下技术:
1. 对于框架版本 1.9 及更高版本,应通过在队列对象的WDF_OBJECT_ATTRIBUTES结构中设置 WdfSynchronizationScopeQueue,为单个队列启用队列级同步。 这是首选技术。
2. 或者,可以在所有框架版本中使用以下步骤:
- 在设备对象的WDF_OBJECT_ATTRIBUTES结构中,将 SynchronizationScope 设置为 WdfSynchronizationScopeQueue;
- 为每个设备的队列对象使用默认的 WdfSynchronizationScopeInheritFromParent 值;
如果不希望框架同步处理驱动程序 I/O 请求的回调函数,请使用驱动程序、设备和队列对象的默认 SynchronizationScope 值。 在这种情况下,框架不会自动同步驱动程序的 I/O 请求相关的回调函数,并且可以在 IRQL <= DISPATCH_LEVEL调用回调函数。
请注意,设置 SynchronizationScope 值只会同步上一个表包含的回调函数。 如果希望框架同时同步驱动程序的中断、DPC、工作项和计时器对象回调函数,驱动程序必须将这些对象的配置结构的 AutomaticSerialization 成员设置为 TRUE。
但是,仅当要同步的所有回调函数都在同一 IRQL 上运行时,才能将 AutomaticSerialization 设置为 TRUE 。 选择 执行级别可能会导致不兼容的 IRQL 级别。 在这种情况下,驱动程序必须使用 框架锁 ,而不是设置 AutomaticSerialization。
如果将 AutomaticSerialization 设置为 TRUE,则应选择队列级同步。
选择执行级别
当驱动程序创建某些类型的框架对象时,它可以指定对象的 执行级别 。 执行级别指定 IRQL,框架将在其中调用对象的事件回调函数,用于处理驱动程序的 I/O 请求。
如果驱动程序提供执行级别,则提供的级别会影响队列和文件对象的回调函数。 通常,如果驱动程序使用自动同步,框架会在 IRQL = DISPATCH_LEVEL调用这些回调函数。 通过指定执行级别,驱动程序可以强制框架在 IRQL = PASSIVE_LEVEL 调用这些回调函数。 在设置调用队列和文件对象回调函数的 IRQL 时,框架使用以下规则:
- 如果驱动程序使用自动同步,则其队列和文件对象回调函数在 IRQL = DISPATCH_LEVEL调用,除非驱动程序要求框架在 IRQL = PASSIVE_LEVEL 调用其回调函数;
- 如果驱动程序未使用自动同步并且未指定执行级别,则可以在 IRQL <= DISPATCH_LEVEL调用驱动程序的队列和文件对象回调函数;
请注意,如果驱动程序提供文件对象回调函数,则很可能希望框架在 IRQL = PASSIVE_LEVEL 调用这些回调函数,因为某些文件数据(如文件名)可分页。
若要提供执行级别,驱动程序必须为对象的WDF_OBJECT_ATTRIBUTES结构的 ExecutionLevel 成员指定值。 驱动程序可以指定的执行级别值包括:
- WdfExecutionLevelPassive:框架在 IRQL = PASSIVE_LEVEL 调用对象的回调函数;
- WdfExecutionLevelDispatch:框架可以在 IRQL <= DISPATCH_LEVEL 调用对象的回调函数。 如果驱动程序使用自动同步,框架始终在 IRQL = DISPATCH_LEVEL调用回调函数;
- WdfExecutionLevelInheritFromParent:框架从对象的父级获取对象的 ExecutionLevel 值;
驱动程序对象的默认执行级别为 WdfExecutionLevelDispatch。 所有其他对象的默认执行级别为 WdfExecutionLevelInheritFromParent。
下表显示了框架可以调用队列对象和文件对象的驱动程序回调函数的 IRQL 级别。
可以将驱动程序、设备、文件、队列、计时器和常规对象的执行级别设置为 WdfExecutionLevelPassive 或 WdfExecutionLevelDispatch 。 对于其他对象,仅允许 WdfExecutionLevelInheritFromParent 。
在以下的情况下,应指定 WdfExecutionLevelPassive :
- 驱动程序的回调函数必须调用框架方法或 Windows 驱动程序模型 (WDM) 例程,这些例程只能在 IRQL = PASSIVE_LEVEL 调用;
- 驱动程序的回调函数必须访问可分页代码或数据。 例如,文件对象回调函数通常访问可分页的 data;
驱动程序可以设置 WdfExecutionLevelDispatch,并提供回调函数,如果它必须在 IRQL = PASSIVE_LEVEL 处理某些操作,则创建工作项,而不是设置 WdfExecutionLevelPassive。
在决定驱动程序是否应将对象的执行级别设置为 WdfExecutionLevelPassive 之前,应确定调用驱动程序和驱动程序堆栈中其他驱动程序的 IRQL。 请考虑以下情况:
- 如果驱动程序位于内核模式驱动程序堆栈的顶部,则系统通常会在 IRQL = PASSIVE_LEVEL 调用驱动程序。 此类驱动程序的客户端可能是基于 UMDF 的驱动程序或用户模式应用程序。 指定 WdfExecutionLevelPassive 不会对驱动程序的性能产生负面影响,因为框架不必将驱动程序对 IRQL = PASSIVE_LEVEL 调用的工作项的调用排队;
- 如果驱动程序不在堆栈顶部,系统可能不会在 IRQL = PASSIVE_LEVEL 调用驱动程序。 因此,框架必须将驱动程序对工作项的调用排队,这些工作项稍后在 IRQL = PASSIVE_LEVEL调用。 与允许在 IRQL <= DISPATCH_LEVEL 调用驱动程序的回调函数相比,此过程可能会导致驱动程序性能不佳;
对于 DPC 对象以及不表示被动级别计时器的计时器对象,请注意,如果将父设备的执行级别设置为 WdfExecutionLevelPassive,则无法将配置结构的 AutomaticSerialization 成员设置为 TRUE。 这是因为框架将在 IRQL = PASSIVE_LEVEL 获取设备对象的 回调同步锁 ,因此锁不能用于同步 DPC 或计时器对象回调函数,这些函数必须在 IRQL = DISPATCH_LEVEL执行。 在这种情况下,驱动程序应在必须彼此同步的任何设备、DPC 或计时器对象回调函数中使用 框架旋转锁 。
另请注意,对于表示被动级别计时器的计时器对象,仅当父设备的执行级别设置为 WdfExecutionLevelPassive 时,才能将配置结构的 AutomaticSerialization 成员设置为 TRUE。
使用框架锁
有时,驱动程序必须提供与 I/O 请求相关的回调函数的特定于驱动程序的同步,或者作为框架提供的同步的替代。 驱动程序可以使用回调同步锁、旋转锁、等待锁和中断锁来同步驱动程序代码。
回调同步锁
如果已将驱动程序设置为使用框架的 自动同步 功能,则框架在调用驱动程序的 I/O 请求相关事件回调函数之前获取同步锁。
驱动程序也可以获取与框架设备对象和队列对象关联的 这些回调同步锁。 若要获取同步锁,驱动程序会调用 WdfObjectAcquireLock。 若要释放锁,驱动程序会调用 WdfObjectReleaseLock。
如果驱动程序使用框架的设备级或队列级 I/O 请求相关回调函数同步,但必须将在 IRQL = PASSIVE_LEVEL 上运行的某些代码与在 IRQL = DISPATCH_LEVEL 运行的回调函数同步,则你可能希望驱动程序使用回调同步锁。 这是因为驱动程序只能对在同一 IRQL 处执行的回调函数使用自动同步。
例如,仅当工作项对象的父对象的执行级别为 WdfExecutionLevelPassive (时,驱动程序才能对工作项对象使用自动同步,因为工作项的回调函数始终在 IRQL= PASSIVE_LEVEL) 执行。 因此,如果驱动程序在设备对象的 WDF_OBJECT_ATTRIBUTES 结构的 ExecutionLevel 成员中指定 WdfExecutionLevelDispatch,则驱动程序无法设置子工作项对象的配置结构的 AutomaticSerialization 成员。 相反,驱动程序必须获取回调同步锁才能将 EvtWorkItem 回调函数与父设备对象的回调函数同步。
框架等待锁
使用框架等待锁从 IRQL = PASSIVE_LEVEL 运行的代码同步对驱动程序数据的访问。 在驱动程序可以使用框架等待锁之前,它必须调用 WdfWaitLockCreate 来创建等待锁对象。 然后,驱动程序可以调用 WdfWaitLockAcquire 来获取锁,并 调用 WdfWaitLockRelease 来释放它。
框架旋转锁
使用框架旋转锁从 IRQL <= DISPATCH_LEVEL 运行的代码同步对驱动程序数据的访问。 当驱动程序线程获取旋转锁时,系统会将线程的 IRQL 设置为DISPATCH_LEVEL。 当线程释放锁时,系统会将线程的 IRQL 还原到其以前的级别。
如果未使用自动框架同步的驱动程序,则如果上下文空间可写且驱动程序的事件回调函数不止一个访问空间,则可以使用旋转锁来同步对设备对象的上下文空间的访问。
在驱动程序可以使用框架旋转锁之前,它必须调用 WdfSpinLockCreate 来创建旋转锁对象。 然后,驱动程序可以调用 WdfSpinLockAcquire 来获取锁,并 调用 WdfSpinLockRelease 来释放它。
框架中断锁
对于支持 DIRQL 中断处理的中断对象,框架中断锁是旋转锁。 在驱动程序获取中断旋转锁后,驱动程序会在设备的 DIRQL 处执行,直到它释放该锁。 有
对于支持被动级别处理的中断对象,框架中断锁是等待锁。 驱动程序获取中断等待锁后,驱动程序会在 IRQL = PASSIVE_LEVEL处执行,直到释放该锁。 有