Fungsi WdfIoQueueAssignForwardProgressPolicy (wdfio.h)

Artikel
08/08/2023

[Berlaku untuk KMDF saja]

Metode WdfIoQueueAssignForwardProgressPolicy memungkinkan kemampuan kerangka kerja untuk menjamin kemajuan penerusan untuk antrean I/O tertentu.

Sintaks

NTSTATUS WdfIoQueueAssignForwardProgressPolicy(
  [in] WDFQUEUE                              Queue,
  [in] PWDF_IO_QUEUE_FORWARD_PROGRESS_POLICY ForwardProgressPolicy
);

Parameter

[in] Queue

Handel ke objek antrean kerangka kerja.

[in] ForwardProgressPolicy

Penunjuk ke struktur WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY yang dialokasikan driver.

Nilai kembali

WdfIoQueueAssignForwardProgressPolicy mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai ini:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter input tidak valid.
STATUS_INFO_LENGTH_MISMATCH	Ukuran struktur WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY salah.
STATUS_INSUFFICIENT_RESOURCES	Jumlah memori yang tersedia terlalu rendah.

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya. Selain itu, jika fungsi panggilan balik EvtIoAllocateResourcesForReservedRequest driver Anda mengembalikan nilai status kesalahan, WdfIoQueueAssignForwardProgressPolicy mengembalikan nilai tersebut.

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

Keterangan

MetodeWdfIoQueueAssignForwardProgressPolicy membuat objek permintaan yang dicadangkan kerangka kerja untuk situasi memori rendah dan mendaftarkan fungsi panggilan balik yang dipanggil kerangka kerja untuk menangani situasi memori rendah.

Dalam KMDF versi 1.9, antrean I/O yang diwakili parameter Antrean harus merupakan antrean I/O default perangkat, atau antrean yang driver Anda panggil WdfDeviceConfigureRequestDispatching. Driver dapat memanggil WdfIoQueueAssignForwardProgressPolicy kapan saja setelah disebut WdfDeviceConfigureRequestDispatching.

Dalam KMDF versi 1.11 dan yang lebih baru, antrean I/O yang diwakili parameter Antrean dapat berupa antrean apa pun yang menerima permintaan langsung dari kerangka kerja. Misalnya, driver mungkin menentukan antrean yang akan meneruskan IRP secara dinamis.

Sebelum WdfIoQueueAssignForwardProgressPolicy kembali, kerangka kerja melakukan hal berikut:

Membuat dan menyimpan jumlah objek permintaan yang telah ditentukan driver untuk anggota TotalForwardProgressRequests dari struktur WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY .
Jika driver sebelumnya disebut WdfDeviceInitSetRequestAttributes, setiap alokasi menyertakan ruang konteks yang ditentukan WdfDeviceInitSetRequestAttributes .
Memanggil fungsi panggilan balik EvtIoAllocateResourcesForReservedRequest driver untuk setiap objek permintaan yang dibuat kerangka kerja.

Setelah driver memanggil WdfIoQueueAssignForwardProgressPolicy untuk membuat objek permintaan yang dipesan, kerangka kerja menggunakan objek yang dipesan tersebut setiap kali upayanya untuk membuat objek permintaan baru gagal. (Biasanya, kegagalan tersebut disebabkan oleh situasi memori yang rendah.)

Kerangka kerja menghapus objek permintaan yang dipesan hanya ketika menghapus objek antrean kerangka kerja tempat objek tersebut berada. Jika driver Anda memanggil fungsi panggilan balik WdfDeviceInitSetRequestAttributes dan menentukan fungsi panggilan balik EvtCleanupCallback atau EvtDestroyCallback untuk objek permintaannya, kerangka kerja memanggil fungsi panggilan balik ini untuk objek permintaan yang dicadangkan saat menghapus objek.

Untuk informasi selengkapnya tentang metode WdfIoQueueAssignForwardProgressPolicy dan cara menggunakan kemampuan kemajuan maju kerangka kerja yang dijamin, lihat Menjamin Kemajuan Maju Operasi I/O.

Contoh

Contoh kode ini mengonfigurasi antrean I/O yang dibuat sebelumnya untuk menerima permintaan tulis, lalu memungkinkan kemajuan penerusan yang dijamin untuk antrean.

#define MAX_RESERVED_REQUESTS 10

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY queueForwardProgressPolicy;
WDFQUEUE writeQueue;
NTSTATUS status = STATUS_SUCCESS;
...
status = WdfDeviceConfigureRequestDispatching(
             device,
             writeQueue,
             WdfRequestTypeWrite
             );
if(!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY_DEFAULT_INIT(
    &queueForwardProgressPolicy,
    MAX_RESERVED_REQUESTS
    );
status = WdfIoQueueAssignForwardProgressPolicy(
             writeQueue,
             &queueForwardProgressPolicy
             );
if(!NT_SUCCESS(status)) {
    return status;
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1.9
Header	wdfio.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf)

Lihat juga

EvtIoAllocateResourcesForReservedRequest

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY

WdfDeviceConfigureRequestDispatching

Bagikan melalui