Функция 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 , инициализированную вызовом WDF_INTERRUPT_CONFIG_INIT.

[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 был вызван после запуска устройства. WdfInterruptCreate также возвращает это значение, если подпрограмма обратного вызова драйвера EVT_WDF_DEVICE_PREPARE_HARDWARE вызывает WdfInterruptCreate с элементами InterruptRaw и InterruptTranslatedструктуры WDF_INTERRUPT_CONFIG , имеющими значение NULL.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти.
STATUS_WDF_PARENT_ASSIGNMENT_NOT_ALLOWED	В KMDF версии 1.9 или более ранней драйвер указал значение, отличное от NULL , для элемента ParentObjectструктуры WDF_OBJECT_ATTRIBUTES . В KMDF версии 1.11 или более поздней драйвер указал значение, отличное от устройства платформы или очереди, для элемента ParentObjectструктуры WDF_OBJECT_ATTRIBUTES .
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Для элемента AutomaticSerialization структуры WDF_INTERRUPT_CONFIG задано значение TRUE и одно из следующих значений: Уровень выполнения родительского объекта прерывания — WdfExecutionLevelPassive , и драйвер предоставил EvtInterruptDpc. Уровень выполнения родительского объекта прерывания — WdfExecutionLevelDispatch , и драйвер предоставил EvtInterruptWorkItem. Дополнительные сведения см. в разделе WDF_INTERRUPT_CONFIG.
STATUS_NOT_SUPPORTED	Драйвер запросил обработку прерываний пассивного уровня на платформе раньше, чем Windows 8.

Список других возвращаемых значений, которые может возвращать метод WdfInterruptCreate , см. в разделе Ошибки создания объекта платформы.

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Драйверы обычно вызывают метод WdfInterruptCreate из функции обратного вызова EvtDriverDeviceAdd . Начиная с KMDF версии 1.11 и UMDF версии 2.0 драйверы могут вызывать WdfInterruptCreate из EvtDevicePrepareHardware. Если драйвер вызывает WdfInterruptCreate из EvtDriverDeviceAdd, элементы InterruptRaw и InterruptTranslated структуры WDF_INTERRUPT_CONFIG должны иметь значение NULL. Если драйвер вызывает WdfInterruptCreate из EvtDevicePrepareHardware, эти члены должны быть допустимыми.

Если вы создаете объект прерывания с поддержкой пробуждения, как описано в разделе Использование прерывания для пробуждения устройства, необходимо вызвать WdfInterruptCreate из EvtDevicePrepareHardware.

Драйвер должен вызывать WdfInterruptCreate один раз для каждого вектора прерывания, необходимого его устройству. Если устройство поддерживает прерывания с сигналом о сообщениях (MSI), драйвер должен создать объект прерывания для каждого сообщения, которое может поддерживать устройство.

После того как диспетчер PnP назначает системные ресурсы устройству, платформа сохраняет сведения о ресурсах прерываний, назначенных устройству, в созданных драйвером объектах прерываний. (Драйверы, которые не поддерживают Plug and Play, не могут использовать объекты прерываний.)

Система может не назначать все ресурсы прерываний, которые может поддерживать устройство. Например, драйвер создаст восемь объектов прерываний для устройства, которое поддерживает восемь сообщений MSI. Однако система может назначить устройству только одно сообщение. В этом случае семь объектов прерывания будут неиспользуемы.

Как правило, драйвер должен хранить сведения, относящиеся к прерыванию, например скопированное содержимое регистров прерываний устройства, в контекстном пространстве объекта прерывания. Структура WDF_OBJECT_ATTRIBUTES , которую драйвер передает в WdfInterruptCreate , должна описывать контекстное пространство.

Для драйверов, использующих платформу версии 1.9 и более ранних версий, родительским элементом каждого объекта прерывания является объект устройства, которому принадлежит прерывание. Драйвер не может изменить этот родительский элемент, а элемент ParentObjectструктуры WDF_OBJECT_ATTRIBUTES должен иметь значение NULL. Начиная с версии 1.11 ParentObject может быть объектом устройства платформы или объектом очереди. Если драйвер указывает родительский элемент, драйвер должен задать для элемента AutomaticSerialization структуры конфигурации значение TRUE. Драйвер может указать родительский объект как для прерываний в DIRQL, так и для прерываний пассивного уровня.

Если драйвер предоставляет функции обратного вызова EvtCleanupCallback или EvtDegradCallback для объекта прерывания платформы, обратите внимание, что платформа вызывает эти функции обратного вызова в 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)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)