Fungsi WdfInterruptCreate (wdfinterrupt.h)

Artikel
02/27/2024

[Berlaku untuk KMDF dan UMDF]

Metode WdfInterruptCreate membuat objek interupsi kerangka kerja.

Sintaks

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

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja.

[in] Configuration

Penunjuk ke struktur WDF_INTERRUPT_CONFIG yang diinisialisasi oleh panggilan ke WDF_INTERRUPT_CONFIG_INIT.

[in, optional] Attributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang menentukan atribut objek untuk objek interupsi kerangka kerja. (Lihat Keterangan untuk informasi tambahan.) Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.

[out] Interrupt

Penunjuk ke lokasi yang menerima handel ke objek interupsi baru.

Nilai kembali

WdfInterruptCreate mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut.

Menampilkan kode	Deskripsi
STATUS_INFO_LENGTH_MISMATCH	Ukuran struktur WDF_INTERRUPT_CONFIG salah.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid ditentukan.
STATUS_INVALID_DEVICE_STATE	WdfInterruptCreate dipanggil setelah perangkat dimulai. WdfInterruptCreate juga mengembalikan nilai ini jika rutinitas panggilan balik EVT_WDF_DEVICE_PREPARE_HARDWARE driver memanggil WdfInterruptCreate dengan anggota InterruptRaw dan InterruptTranslated dari struktur WDF_INTERRUPT_CONFIG yang diatur ke NULL.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup.
STATUS_WDF_PARENT_ASSIGNMENT_NOT_ALLOWED	Di KMDF versi 1.9 atau yang lebih lama, driver menentukan nilai non-NULL untuk anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES . Di KMDF versi 1.11 atau yang lebih baru, driver menentukan nilai selain perangkat kerangka kerja atau antrean untuk anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES .
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Anggota AutomaticSerialization dari struktur WDF_INTERRUPT_CONFIG diatur ke TRUE dan: Tingkat eksekusi objek induk interupsi adalah WdfExecutionLevelPassive dan driver telah memasok EvtInterruptDpc. Tingkat eksekusi objek induk interupsi adalah WdfExecutionLevelDispatch dan driver telah memasok EvtInterruptWorkItem. Untuk informasi selengkapnya, lihat WDF_INTERRUPT_CONFIG.
STATUS_NOT_SUPPORTED	Driver meminta penanganan gangguan tingkat pasif pada platform yang lebih awal dari Windows 8.

Untuk daftar nilai pengembalian lain yang mungkin dikembalikan oleh metode WdfInterruptCreate , lihat Kesalahan Pembuatan Objek Kerangka Kerja.

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Driver biasanya memanggil metode WdfInterruptCreate dari fungsi panggilan balik EvtDriverDeviceAdd . Mulai dari KMDF versi 1.11 dan UMDF versi 2.0, driver dapat memanggil WdfInterruptCreate dari EvtDevicePrepareHardware. Jika driver memanggil WdfInterruptCreate dari EvtDriverDeviceAdd, anggota InterruptRaw dan InterruptTranslated dari struktur WDF_INTERRUPT_CONFIG harus NULL. Jika driver memanggil WdfInterruptCreate dari EvtDevicePrepareHardware, kedua anggota ini harus valid.

Jika Anda membuat objek interupsi berkemampuan bangun, seperti yang dijelaskan dalam Menggunakan Interupsi untuk Membangunkan Perangkat, Anda harus memanggil WdfInterruptCreate dari EvtDevicePrepareHardware.

Driver Anda harus memanggil WdfInterruptCreate sekali untuk setiap vektor interupsi yang diperlukan perangkatnya. Jika perangkat mendukung interupsi bertanda pesan (MSI), driver harus membuat objek interupsi untuk setiap pesan yang dapat didukung perangkat.

Setelah manajer PnP menetapkan sumber daya sistem ke perangkat, kerangka kerja menyimpan informasi tentang sumber daya interupsi yang ditetapkan perangkat di objek interupsi yang telah dibuat driver. (Driver yang tidak mendukung Plug and Play tidak dapat menggunakan objek interupsi.)

Sistem mungkin tidak menetapkan semua sumber daya interupsi yang dapat didukung perangkat. Misalnya, driver akan membuat delapan objek interupsi untuk perangkat yang mampu mendukung delapan pesan MSI. Namun, sistem mungkin hanya menetapkan satu pesan ke perangkat. Dalam hal ini, tujuh objek interupsi tidak akan digunakan.

Biasanya, driver Anda harus menyimpan informasi khusus interupsi, seperti konten register interupsi perangkat yang disalin, di ruang konteks objek interupsi. Struktur WDF_OBJECT_ATTRIBUTES yang diteruskan driver ke WdfInterruptCreate harus menggambarkan ruang konteks.

Untuk driver yang menggunakan kerangka kerja versi 1.9 dan yang lebih lama, induk dari setiap objek interupsi adalah objek perangkat tempat gangguan berada. Driver tidak dapat mengubah induk ini, dan anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES harus NULL. Mulai versi 1.11, ParentObject dapat menjadi objek perangkat kerangka kerja atau objek antrean. Jika driver menentukan induk, driver harus mengatur anggota AutomaticSerialization dari struktur konfigurasi ke TRUE. Driver dapat menentukan induk untuk gangguan di DIRQL dan interupsi tingkat pasif.

Jika driver Anda menyediakan fungsi panggilan balik EvtCleanupCallback atau EvtDestroyCallback untuk objek gangguan kerangka kerja, perhatikan bahwa kerangka kerja memanggil fungsi panggilan balik ini di IRQL = PASSIVE_LEVEL.

Untuk informasi selengkapnya tentang penanganan gangguan dalam driver berbasis kerangka kerja, lihat Menangani Gangguan Perangkat Keras.

Contoh

Contoh kode berikut menginisialisasi struktur WDF_INTERRUPT_CONFIG dan struktur WDF_OBJECT_ATTRIBUTES lalu memanggil 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
                            );

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfinterrupt.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)