WdfInterruptCreate 函数 (wdfinterrupt.h)

项目
08/08/2023

[适用于 KMDF 和 UMDF]

WdfInterruptCreate 方法创建框架中断对象。

语法

NTSTATUS WdfInterruptCreate(
  [in]           WDFDEVICE              Device,
  [in]           PWDF_INTERRUPT_CONFIG  Configuration,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]          WDFINTERRUPT           *Interrupt
);

参数

[in] Device

框架设备对象的句柄。

[in] Configuration

指向通过调用 WDF_INTERRUPT_CONFIG_INIT 初始化的WDF_INTERRUPT_CONFIG 结构的指针。

[in, optional] Attributes

指向 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构指定框架中断对象的对象属性。 (请参阅备注了解其他信息。) 此参数是可选的，可以WDF_NO_OBJECT_ATTRIBUTES。

[out] Interrupt

指向接收新中断对象的句柄的位置的指针。

返回值

如果操作成功，WdfInterruptCreate 将返回STATUS_SUCCESS。否则，此方法可能会返回以下值之一。

返回代码	说明
STATUS_INFO_LENGTH_MISMATCH	WDF_INTERRUPT_CONFIG结构的大小不正确。
STATUS_INVALID_PARAMETER	指定的参数无效。
STATUS_INVALID_DEVICE_STATE	WdfInterruptCreate 是在设备启动后调用的。如果驱动程序的EVT_WDF_DEVICE_PREPARE_HARDWARE回调例程调用 WdfInterruptCreate 且WDF_INTERRUPT_CONFIG结构的 InterruptRaw 和 InterruptTranslated 成员设置为 NULL，WdfInterruptCreate 也会返回此值。
STATUS_INSUFFICIENT_RESOURCES	内存不足。
STATUS_WDF_PARENT_ASSIGNMENT_NOT_ALLOWED	在 KMDF 版本 1.9 或更早版本中，驱动程序为 WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员指定了非 NULL 值。在 KMDF 版本 1.11 或更高版本中，驱动程序为 WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员指定了框架设备或队列以外的值。
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	WDF_INTERRUPT_CONFIG 结构的 AutomaticSerialization 成员设置为 TRUE，并可以：中断的父对象的执行级别为 WdfExecutionLevelPassive ，驱动程序已提供 EvtInterruptDpc。中断的父对象的执行级别为 WdfExecutionLevelDispatch ，驱动程序已提供 EvtInterruptWorkItem。有关详细信息，请参阅 WDF_INTERRUPT_CONFIG。
STATUS_NOT_SUPPORTED	驱动程序在早于 Windows 8 的平台上请求被动级中断处理。

有关 WdfInterruptCreate 方法可能返回的其他返回值的列表，请参阅框架对象创建错误。

此方法还可能返回其他 NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

驱动程序通常从 EvtDriverDeviceAdd 回调函数调用 WdfInterruptCreate 方法。从 KMDF 版本 1.11 和 UMDF 版本 2.0 开始，驱动程序可以从 EvtDevicePrepareHardware 调用 WdfInterruptCreate。如果驱动程序从 EvtDriverDeviceAdd 调用 WdfInterruptCreate，则 WDF_INTERRUPT_CONFIG 结构的 InterruptRaw 和 InterruptTranslated 成员必须为 NULL。如果驱动程序从 EvtDevicePrepareHardware 调用 WdfInterruptCreate，则这两个成员都必须有效。

如果要创建支持唤醒的中断对象（如使用中断唤醒设备中所述），则必须从 EvtDevicePrepareHardware 调用 WdfInterruptCreate。

驱动程序必须为其设备所需的每个中断向量调用 一次 WdfInterruptCreate 。如果设备支持 msi) (消息信号中断，则驱动程序必须为设备可以支持的每个消息创建中断对象。

PnP 管理器将系统资源分配给设备后，框架会将有关设备分配的中断资源的信息存储在驱动程序创建的中断对象中。不支持即插即用的 ( 驱动程序无法使用中断对象。)

系统可能不会分配设备可以支持的所有中断资源。例如，驱动程序将为能够支持 8 条 MSI 消息的设备创建 8 个中断对象。但是，系统可能只向设备分配一条消息。在这种情况下，将不使用其中七个中断对象。

通常，驱动程序应将特定于中断的信息（例如设备中断寄存器的复制内容）存储在中断对象的上下文空间中。驱动程序传递给 WdfInterruptCreate的WDF_OBJECT_ATTRIBUTES结构应描述上下文空间。

对于使用框架版本 1.9 及更早版本的驱动程序，每个中断对象的父对象是中断所属的设备对象。驱动程序无法更改此父级，并且 WDF_OBJECT_ATTRIBUTES 结构的 ParentObject 成员必须为 NULL。从版本 1.11 开始， ParentObject 可以是框架设备对象或队列对象。如果驱动程序指定父级，则驱动程序必须将配置结构的 AutomaticSerialization 成员设置为 TRUE。驱动程序可以为 DIRQL 中的中断和被动级中断指定父级。

如果驱动程序为框架中断对象提供 EvtCleanupCallback 或 EvtDestroyCallback 回调函数，请注意，框架在 IRQL = PASSIVE_LEVEL调用这些回调函数。

有关在基于框架的驱动程序中处理中断的详细信息，请参阅处理硬件中断。

示例

下面的代码示例初始化 WDF_INTERRUPT_CONFIG 结构和 WDF_OBJECT_ATTRIBUTES 结构，然后调用 WdfInterruptCreate。

NTSTATUS  status;
WDF_INTERRUPT_CONFIG  interruptConfig;
WDF_OBJECT_ATTRIBUTES  interruptAttributes;

WDF_INTERRUPT_CONFIG_INIT(
                          &interruptConfig,
                          MyEvtInterruptIsr,
                          MyEvtInterruptDpc
                          );
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &interruptAttributes,
                                        INTERRUPT_DATA
                                        );
status = WdfInterruptCreate(
                            device,
                            &interruptConfig,
                            &interruptAttributes,
                            &devExt->WdfInterrupt
                            );

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
标头	wdfinterrupt.h (包括 Wdf.h)
Library	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI 符合性规则	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)