PGET_SCATTER_GATHER_LIST_EX fungsi panggilan balik (wdm.h)

Artikel
03/08/2023

Rutinitas GetScatterGatherListEx mengalokasikan sumber daya yang diperlukan untuk transfer DMA, membangun daftar sebar/kumpulkan, dan memanggil rutinitas AdapterListControl yang disediakan driver untuk memulai transfer DMA.

Perhatian

Jangan panggil rutinitas ini untuk perangkat DMA sistem.

Sintaks

PGET_SCATTER_GATHER_LIST_EX PgetScatterGatherListEx;

NTSTATUS PgetScatterGatherListEx(
  [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, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PSCATTER_GATHER_LIST *ScatterGatherList
)
{...}

Parameter

[in] DmaAdapter

Penunjuk ke struktur DMA_ADAPTER . Struktur ini adalah objek adaptor yang mewakili perangkat DMA master bus driver. Penelepon 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 rutinitas CancelAdapterChannel .

[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 parameter Offset dan Length . Untuk informasi selengkapnya tentang rantai MDL, lihat Menggunakan MDL.

[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

Panjang, 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	Makna
DMA_SYNCHRONOUS_CALLBACK	Rutinitas GetScatterGatherListEx disebut secara sinkron. Jika bendera ini diatur, dan sumber daya DMA yang diperlukan tidak segera tersedia, panggilan gagal dan mengembalikan STATUS_INSUFFICIENT_RESOURCES.

Jika bendera DMA_SYNCHRONOUS_CALLBACK diatur, parameter ExecutionRoutine bersifat opsional dan dapat berupa NULL. Jika bendera ini tidak diatur, ExecutionRoutine harus merupakan penunjuk non-NULL yang valid. Untuk informasi selengkapnya tentang bendera ini, lihat bagian Keterangan.

[in, optional] ExecutionRoutine

Penunjuk 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 DMA_SYNCHRONOUS_CALLBACK diatur, parameter ExecutionRoutine bersifat opsional dan dapat berupa NULL. Jika parameter ini NULL, pemanggil dapat menggunakan sumber daya yang dialokasikan oleh GetScatterGatherListEx untuk melakukan transfer DMA setelah GetScatterGatherListEx kembali. Untuk informasi lebih lanjut, lihat bagian Keterangan.

[in, optional] Context

Konteks kontrol adaptor yang ditentukan driver. Konteks ini diteruskan ke rutinitas AdapterListControl sebagai parameter Konteks .

[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, optional] DmaCompletionRoutine

Tidak digunakan. Atur ke NULL.

[in, optional] CompletionContext

Tidak digunakan. Atur ke NULL.

[out, optional] ScatterGatherList

Penunjuk ke variabel tempat rutin menulis penunjuk ke daftar sebar/kumpulkan yang dialokasikan. Parameter ini menunjuk ke struktur SCATTER_GATHER_LIST . Rutinitas mengalokasikan struktur ini dan array SCATTER_GATHER_ELEMENT yang diarahkannya.

Parameter ScatterGatherList bersifat opsional dan dapat berupa NULL jika parameter ExecutionRoutine bukan NULL.

Jika bendera DMA_SYNCHRONOUS_CALLBACK diatur dan parameter ExecutionRoutine adalah NULL, ScatterGatherList harus menjadi penunjuk non-NULL yang valid. Jika ExecutionRoutine bukan NULL, ScatterGatherList bersifat opsional dan dapat berupa NULL jika driver panggilan tidak memerlukan daftar sebar/kumpulkan. Panggilan GetScatterGatherListEx gagal jika bendera DMA_SYNCHRONOUS_CALLBACK diatur dan ScatterGatherList dan ExecutionRoutine adalah NULL, atau jika bendera DMA_SYNCHRONOUS_CALLBACK tidak diatur dan ExecutionRoutine adalah NULL.

Nilai kembali

GetScatterGatherListEx mengembalikan STATUS_SUCCESS jika panggilan berhasil. Kemungkinan nilai pengembalian kesalahan mencakup kode status berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETERS	Rutinitas gagal karena nilai parameter yang tidak valid yang diteruskan oleh pemanggil.
STATUS_INSUFFICIENT_RESOURCES	Rutinitas gagal mengalokasikan sumber daya yang diperlukan untuk transfer DMA.

Keterangan

GetScatterGatherListEx bukanlah rutinitas sistem yang dapat dipanggil langsung berdasarkan nama. Rutinitas ini hanya dapat dipanggil dengan penunjuk dari alamat yang dikembalikan dalam struktur DMA_OPERATIONS . Driver mendapatkan alamat rutinitas ini dengan memanggil IoGetDmaAdapter dengan anggota Versi parameter DeviceDescription diatur ke DEVICE_DESCRIPTION_VERSION3. Jika IoGetDmaAdapter mengembalikan NULL, rutinitas tidak tersedia di platform Anda.

Gunakan GetScatterGatherListEx hanya untuk adaptor master bus. Jangan gunakan rutinitas ini untuk adaptor DMA sistem.

Driver perangkat master bus dapat menggunakan GetScatterGatherListEx untuk menggabungkan operasi yang dilakukan oleh rutinitas AllocateAdapterChannelEx dan MapTransferEx ke dalam satu panggilan. GetScatterGatherListEx melakukan operasi berikut:

Mengalokasikan sumber daya yang diperlukan untuk transfer DMA.
Menyusun daftar sebar/kumpulkan berdasarkan nilai parameter Mdl, Offset, dan Length .
Memanggil rutinitas AdapterListControl yang disediakan driver dan memasok daftar sebar/kumpulkan ke rutinitas ini sebagai parameter.

Sumber daya yang dialokasikan secara otomatis dirilis setelah adapterListControl rutin kembali. Jika GetScatterGatherListEx dipanggil secara sinkron (yaitu, jika bendera DMA_SYNCHRONOUS_CALLBACK diatur), rutinitas AdapterListControl dapat dihilangkan. Dalam hal ini, pemanggil menggunakan sumber daya yang dialokasikan untuk memulai transfer DMA setelah GetScatterGatherListEx kembali. Pemanggil harus secara eksplisit merilis sumber daya ini.

Secara default, GetScatterGatherListEx 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 rutinitas CancelAdapterChannel .

Jika driver panggilan mengatur bendera DMA_SYNCHRONOUS_CALLBACK , getScatterGatherListEx berperilaku sebagai berikut:

Jika sumber daya yang diminta tidak segera tersedia, GetScatterGatherListEx tidak menunggu sumber daya, tidak membuat daftar sebar/kumpulkan, dan tidak memanggil rutinitas AdapterListControl . Sebaliknya, GetScatterGatherListEx 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 GetScatterGatherListEx kembali.
Jika driver tidak menyediakan rutinitas AdapterListControl , driver dapat menggunakan sumber daya yang dialokasikan dan daftar sebar/kumpulkan setelah GetScatterGatherListEx kembali. Dalam hal ini, driver harus menyediakan penunjuk ScatterGatherList non-NULL yang valid. Selain itu, setelah driver memulai transfer DMA, driver harus memanggil rutinitas FreeAdapterObject untuk membebaskan sumber daya yang dialokasikan GetScatterGatherListEx untuk objek adaptor.

GetScatterGatherListEx adalah versi yang diperluas dari rutinitas GetScatterGatherList . Fitur berikut hanya tersedia dalam versi yang diperluas:

GetScatterGatherListEx mirip dengan rutinitas BuildScatterGatherListEx , kecuali bahwa GetScatterGatherListEx secara otomatis mengalokasikan buffer untuk daftar sebar/kumpulkan.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 8.
Target Platform	Desktop
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL