PBUILD_SCATTER_GATHER_LIST_EX fungsi panggilan balik (wdm.h)
BuildScatterGatherListEx rutin mengalokasikan sumber daya yang diperlukan untuk transfer DMA, membangun daftar sebar/kumpulkan, dan memanggil rutinitas AdapterListControl yang disediakan driver untuk memulai transfer DMA.
Hati
Jangan panggil rutinitas ini untuk perangkat DMA sistem.
Sintaksis
PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;
NTSTATUS PbuildScatterGatherListEx(
[in] PDMA_ADAPTER DmaAdapter,
[in] PDEVICE_OBJECT DeviceObject,
[in] PVOID DmaTransferContext,
[in] PMDL Mdl,
[in] ULONGLONG Offset,
[in] ULONG Length,
[in] ULONG Flags,
[in, optional] PDRIVER_LIST_CONTROL ExecutionRoutine,
[in, optional] PVOID Context,
[in] BOOLEAN WriteToDevice,
[in] PVOID ScatterGatherBuffer,
[in] ULONG ScatterGatherLength,
[in, optional] PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
[in, optional] PVOID CompletionContext,
[out, optional] PVOID ScatterGatherList
)
{...}
Parameter
[in] DmaAdapter
Penunjuk ke struktur DMA_ADAPTER. Struktur ini adalah objek adaptor yang mewakili perangkat DMA master bus driver atau saluran DMA sistem. Pemanggil memperoleh pointer ini dari panggilan sebelumnya ke rutinitas IoGetDmaAdapter
[in] DeviceObject
Penunjuk ke struktur DEVICE_OBJECT. Struktur ini adalah objek perangkat fisik (PDO) yang mewakili perangkat target untuk operasi DMA yang diminta.
[in] DmaTransferContext
Penunjuk ke konteks transfer DMA yang diinisialisasi. Konteks ini diinisialisasi oleh panggilan sebelumnya ke rutinitas InitializeDmaTransferContext. Konteks ini harus unik di semua permintaan alokasi adaptor. Untuk membatalkan permintaan alokasi yang tertunda, pemanggil harus menyediakan konteks transfer DMA untuk permintaan ke CancelAdapterChannel rutin.
[in] Mdl
Penunjuk ke rantai MDL yang menjelaskan tata letak halaman fisik untuk kumpulan buffer terkunci dalam memori virtual. Daftar sebar/kumpulkan untuk transfer DMA akan menggunakan wilayah memori ini yang ditentukan oleh Offset
[in] Offset
Offset awal untuk transfer DMA sebar/kumpulkan. Parameter ini adalah offset byte dari awal buffer di MDL pertama dalam rantai MDL. Jika MDL dalam rantai MDL menentukan total N byte ruang buffer, nilai Offset yang valid berada dalam rentang 0 hingga N–1.
[in] Length
Ukuran, dalam byte, dari transfer DMA. Jika rantai MDL menentukan total N byte ruang buffer, nilai Panjang yang valid berada dalam rentang 1 hingga N–Offset.
[in] Flags
Bendera alokasi saluran adaptor. Bendera berikut didukung:
Bendera | Arti |
---|---|
DMA_SYNCHRONOUS_CALLBACK | Rutinitas BuildScatterGatherListEx disebut sinkron. Jika bendera ini diatur, dan sumber daya DMA yang diperlukan tidak segera tersedia, panggilan gagal dan mengembalikan STATUS_INSUFFICIENT_RESOURCES. |
Jika bendera
[in, optional] ExecutionRoutine
Pointer ke rutinitas AdapterListControl yang disediakan driver yang memulai transfer DMA untuk driver. Manajer I/O memanggil rutinitas AdapterListControl setelah sumber daya yang diperlukan dialokasikan untuk objek adaptor. Setelah rutinitas AdapterListControl kembali, manajer I/O secara otomatis membebaskan objek adaptor dan sumber daya yang dialokasikan untuk objek ini.
Jika bendera
[in, optional] Context
Konteks kontrol adaptor yang ditentukan driver. Konteks ini diteruskan ke rutinitas
[in] WriteToDevice
Arah transfer DMA. Atur parameter ini ke TRUE untuk operasi tulis, yang mentransfer data dari memori ke perangkat. Atur parameter ini ke FALSE untuk operasi baca, yang mentransfer data dari perangkat ke memori.
[in] ScatterGatherBuffer
Penunjuk ke buffer yang dialokasikan pemanggil tempat rutin menulis daftar sebar/kumpulkan untuk transfer DMA. Daftar ini dimulai dengan struktur SCATTER_GATHER_LIST, yang diikuti oleh array SCATTER_GATHER_ELEMENT.
[in] ScatterGatherLength
Ukuran, dalam byte, dari buffer yang diteruskan dalam parameter
[in, optional] DmaCompletionRoutine
Tidak digunakan. Atur ke NULL.
[in, optional] CompletionContext
Tidak digunakan. Atur ke NULL.
[out, optional] ScatterGatherList
Pointer ke variabel tempat rutin menulis pointer ke daftar sebar/kumpulkan untuk transfer DMA. Daftar ini dimulai dengan struktur SCATTER_GATHER_LIST, yang berisi penunjuk ke array SCATTER_GATHER_ELEMENT. Penunjuk output ini selalu cocok dengan nilai parameter
Jika bendera
Mengembalikan nilai
BuildScatterGatherListEx mengembalikan STATUS_SUCCESS jika panggilan berhasil. Kemungkinan nilai pengembalian kesalahan menyertakan kode status berikut.
Mengembalikan kode | Deskripsi |
---|---|
STATUS_INVALID_PARAMETERS | Rutinitas gagal karena nilai parameter yang tidak valid yang diteruskan oleh pemanggil. |
STATUS_BUFFER_TOO_SMALL | Buffer yang disediakan pemanggil di |
STATUS_INSUFFICIENT_RESOURCES | Rutinitas gagal mengalokasikan sumber daya yang diperlukan untuk transfer DMA. |
Komentar
BuildScatterGatherListEx* bukanlah rutinitas sistem yang dapat dipanggil langsung berdasarkan nama. Rutinitas ini hanya dapat dipanggil oleh pointer dari alamat yang dikembalikan dalam strukturDMA_OPERATIONS* . Driver mendapatkan alamat rutinitas ini dengan memanggil IoGetDmaAdapter
Gunakan BuildScatterGatherListEx hanya untuk adaptor bus-master. Jangan gunakan rutinitas ini untuk adaptor DMA sistem.
BuildScatterGatherListEx mirip dengan rutinitas GetScatterGatherListEx, kecuali memerlukan pemanggil untuk mengalokasikan buffer untuk daftar sebar/kumpulkan.
Misalnya, driver mungkin melakukan pra-alokasi satu atau beberapa buffer sebar/kumpulkan selama inisialisasi perangkat. Nantinya, panggilan BuildScatterGatherListEx yang menggunakan buffer tersebut dapat berhasil dalam kondisi ketersediaan memori rendah yang dapat menyebabkan panggilan GetScatterGatherListEx gagal.
Secara default, BuildScatterGatherListEx mengembalikan secara asinkron, tanpa menunggu alokasi sumber daya yang diminta selesai. Setelah pengembalian ini, pemanggil dapat, jika perlu, membatalkan permintaan alokasi yang tertunda dengan memanggil CancelAdapterChannel rutin.
Jika driver panggilan mengatur bendera DMA_SYNCHRONOUS_CALLBACK, BuildScatterGatherListEx berperilaku sebagai berikut:
Jika sumber daya yang diminta tidak segera tersedia, BuildScatterGatherListEx tidak menunggu sumber daya, tidak membuat daftar sebar/kumpulkan, dan tidak memanggil AdapterListControl rutinitas. Sebaliknya, BuildScatterGatherListEx gagal dan mengembalikan STATUS_INSUFFICIENT_RESOURCES.
Driver tidak diperlukan untuk menyediakan rutinitas AdapterListControl jika bendera DMA_SYNCHRONOUS_CALLBACK diatur.
Jika driver menyediakan rutinitas AdapterListControl, bendera DMA_SYNCHRONOUS_CALLBACK menunjukkan bahwa rutinitas ini akan dipanggil dalam konteks utas panggilan, sebelum BuildScatterGatherListEx kembali.
Jika driver tidak menyediakan rutinitas AdapterListControl, driver dapat menggunakan sumber daya yang dialokasikan dan menyebarkan/mengumpulkan daftar setelah BuildScatterGatherListEx kembali. Dalam hal ini, driver harus menyediakan pointer NULL
ScatterGatherList yang valid dan tidak . Selain itu, setelah transfer DMA yang dimulai driver selesai, driver harus memanggil rutinitas FreeAdapterObject untuk membebaskan sumber daya yang BuildScatterGatherListEx dialokasikan untuk objek adaptor.
Fitur | Deskripsi |
---|---|
Memulai offset | Driver panggilan dapat menentukan offset awal untuk transfer DMA sebar/kumpulkan alih-alih memulai transfer pada alamat buffer pertama di awal rantai MDL. |
Pembatalan permintaan alokasi | Driver dapat memanggil CancelAdapterChannel untuk membatalkan permintaan alokasi yang tertunda ketika adaptor DMA diantrekan untuk menunggu sumber daya DMA. |
Panggilan balik sinkron | Driver dapat mengatur bendera DMA_SYNCHRONOUS_CALLBACK untuk meminta agar rutinitas AdapterListControl yang disediakan driver dipanggil di utas panggilan, sebelum BuildScatterGatherListEx kembali. |
Persyaratan
Syarat | Nilai |
---|---|
klien minimum yang didukung | Tersedia dimulai dengan Windows 8. |
Platform Target |
Desktop |
Header |
wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h) |
IRQL | DISPATCH_LEVEL |
Lihat juga
Menghitung ScatterGatherList
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk