EVT_WDF_IO_QUEUE_IO_STOP fungsi panggilan balik (wdfio.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Fungsi panggilan balik peristiwa EvtIoStop driver selesai, mengantre ulang, atau menangguhkan pemrosesan permintaan tertentu karena antrean I/O permintaan sedang dihentikan.

Sintaks

EVT_WDF_IO_QUEUE_IO_STOP EvtWdfIoQueueIoStop;

void EvtWdfIoQueueIoStop(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request,
  [in] ULONG ActionFlags
)
{...}

Parameter

[in] Queue

Handel ke objek antrean kerangka kerja yang terkait dengan permintaan I/O.

[in] Request

Handel ke objek permintaan kerangka kerja.

[in] ActionFlags

Bitwise ATAU dari satu atau beberapa bendera berjenis WDF_REQUEST_STOP_ACTION_FLAGS yang mengidentifikasi alasan fungsi panggilan balik dipanggil dan apakah permintaan tersebut dapat dibatalkan.

Nilai kembali

Tidak ada

Keterangan

Driver mendaftarkan fungsi panggilan balik EvtIoStop saat memanggil WdfIoQueueCreate. Untuk informasi selengkapnya tentang memanggil WdfIoQueueCreate, lihat Membuat Antrean I/O.

Jika driver mendaftarkan fungsi panggilan balik EvtIoStop untuk antrean I/O, kerangka kerja memanggilnya ketika perangkat yang mendasar antrean membiarkan status berfungsi (D0). Kerangka kerja memanggil fungsi panggilan balik EvtIoStop untuk setiap permintaan I/O yang belum selesai, termasuk permintaan yang dimiliki driver dan yang telah diteruskan ke target I/O.

Dalam kebanyakan kasus, fungsi panggilan balik EvtIoStopmenyelesaikan, membatalkan, atau menunda pemrosesan permintaan I/O lebih lanjut.

Biasanya, driver melakukan salah satu hal berikut:

Jika driver memiliki permintaan I/O, driver memanggil WdfRequestUnmarkCancelable (jika permintaan dapat dibatalkan) dan memanggil WdfRequestStopAcknowledge dengan nilai Antrean Ulang TRUE, atau memanggil WdfRequestComplete dengan nilai status penyelesaian STATUS_SUCCESS atau STATUS_CANCELLED.
Sebelum dapat memanggil metode WdfRequestXxx dengan aman, driver harus memastikan bahwa implementasi EvtIoStop memiliki akses eksklusif ke permintaan.

Untuk melakukan itu, driver harus menyinkronkan akses ke permintaan untuk mencegah utas lain memanipulasi permintaan secara bersamaan. Metode sinkronisasi yang Anda pilih akan bergantung pada desain driver Anda.

Misalnya, jika permintaan ditahan di area konteks bersama, panggilan balik EvtIoStop mungkin memperoleh kunci driver internal, menghapus permintaan dari konteks bersama, lalu melepaskan kunci. Pada titik ini, panggilan balik EvtIoStop memiliki permintaan dan dapat menyelesaikan atau mengantrekan ulang permintaan dengan aman.

Atau, driver menunda pemrosesan lebih lanjut dari permintaan dan memanggil WdfRequestStopAcknowledge dengan nilai Antrean Ulang FALSE.
Jika driver telah meneruskan permintaan I/O ke target I/O, driver dapat memanggil WdfRequestCancelSentRequest untuk mencoba membatalkan permintaan.
Atau, jika driver telah meneruskan permintaan I/O ke driver tingkat bawah di tumpukan drivernya sendiri, dan kerangka kerja memanggil panggilan balik EvtIoStop driver dengan nilai ActionFlagsWdfRequestStopActionSuspend, driver dapat memanggil WdfRequestStopAcknowledge dengan nilai Requeue FALSE. Sebelum melakukannya, driver harus memverifikasi bahwa kondisi berikut terpenuhi:
- Driver yang lebih rendah berhenti memproses semua permintaan I/O yang luar biasa sebagai respons untuk menerima IRP set-power perangkat (Dx).
- Fungsi panggilan balik CompletionRoutine driver dapat menyelesaikan permintaan saat perangkat dalam status daya rendah.

Driver mungkin memilih untuk tidak mengambil tindakan di EvtIoStop untuk permintaan yang dijamin selesai dalam waktu singkat.

Dalam hal ini, kerangka kerja menunggu hingga permintaan yang ditentukan selesai sebelum memindahkan perangkat (atau sistem) ke status daya yang lebih rendah atau menghapus perangkat. Berpotensi, tindakan ini dapat mencegah sistem memasuki status hibernasi atau status daya sistem rendah lainnya. Dalam kasus ekstrem, itu dapat menyebabkan sistem crash dengan kode bugcheck 9F.

Jika bendera WdfRequestStopRequestCancelable diatur dalam parameter ActionFlags , driver harus memanggil WdfRequestUnmarkCancelable sebelum memanggil WdfRequestComplete untuk menyelesaikan (atau membatalkan) permintaan atau WdfRequestStopAcknowledge untuk mengantre ulang permintaan.

Jika driver meneruskan permintaan I/O dari salah satu penangan permintaannya dan menentukan bendera WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET dalam struktur WDF_REQUEST_SEND_OPTIONS permintaan, kerangka kerja tidak memanggil fungsi panggilan balik EvtIoStop driver untuk permintaan ini. Namun, jika driver meneruskan permintaan I/O yang sama dari utas lain, kerangka kerja mungkin memanggil EvtIoStop untuk permintaan ini.

Untuk informasi selengkapnya tentang fungsi panggilan balik EvtIoStop , lihat Menggunakan antrean I/O Power-Managed.

Fungsi panggilan balik ini dapat dipanggil di IRQL <= DISPATCH_LEVEL, kecuali anggota ExecutionLevel dari perangkat atau struktur WDF_OBJECT_ATTRIBUTES driver diatur ke WdfExecutionLevelPassive.

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfio.h (termasuk Wdf.h)
IRQL	<= DISPATCH_LEVEL (lihat bagian Keterangan)