PGET_SCATTER_GATHER_LIST fungsi panggilan balik (wdm.h)

Artikel
02/29/2024

Rutinitas GetScatterGatherList menyiapkan sistem untuk operasi sebar/kumpulkan DMA atas nama objek perangkat target, melalui pengontrol DMA sistem atau adaptor master bus.

Sintaks

PGET_SCATTER_GATHER_LIST PgetScatterGatherList;

NTSTATUS PgetScatterGatherList(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PMDL Mdl,
  [in] PVOID CurrentVa,
  [in] ULONG Length,
  [in] PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in] PVOID Context,
  [in] BOOLEAN WriteToDevice
)
{...}

Parameter

[in] DmaAdapter

Penunjuk ke struktur DMA_ADAPTER yang dikembalikan oleh IoGetDmaAdapter yang mewakili adaptor bus-master atau pengontrol DMA.

[in] DeviceObject

Penunjuk ke objek perangkat yang mewakili perangkat target untuk operasi DMA.

[in] Mdl

Arahkan ke MDL yang menjelaskan buffer di MdlAddress di IRP saat ini.

[in] CurrentVa

Arahkan ke alamat virtual saat ini di MDL agar buffer dipetakan untuk operasi transfer DMA.

[in] Length

Menentukan panjang, dalam byte, yang akan dipetakan.

[in] ExecutionRoutine

Penunjuk ke rutinitas AdapterListControl yang disediakan driver, yang dipanggil pada DISPATCH_LEVEL ketika pengontrol DMA sistem atau adaptor master bus tersedia.

[in] Context

Penunjuk ke konteks yang ditentukan driver yang diteruskan ke rutinitas AdapterListControl driver saat dipanggil.

[in] WriteToDevice

Menunjukkan arah transfer DMA: TRUE untuk transfer dari buffer ke perangkat, dan FALSE sebaliknya.

Nilai kembali

Rutinitas ini dapat mengembalikan salah satu nilai NTSTATUS berikut.

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Operasi berhasil.
STATUS_INSUFFICIENT_RESOURCES	Rutinitas tidak dapat mengalokasikan memori yang cukup atau jumlah register peta yang diperlukan untuk transfer lebih besar dari nilai yang dikembalikan oleh IoGetDmaAdapter.
STATUS_BUFFER_TOO_SMALL	Buffer terlalu kecil untuk transfer yang diminta.

Keterangan

GetScatterGatherList secara dinamis mengalokasikan buffer untuk menyimpan daftar sebar/kumpulkan. Untuk kemungkinan nilai NTSTATUS jika alokasi buffer gagal, lihat nilai yang dikembalikan.

GetScatterGatherList bukanlah rutinitas sistem yang dapat dipanggil langsung berdasarkan nama. Rutinitas ini hanya dapat dipanggil oleh penunjuk dari alamat yang dikembalikan dalam struktur DMA_OPERATIONS . Driver mendapatkan alamat rutinitas ini dengan memanggil IoGetDmaAdapter.

Segera setelah saluran DMA yang sesuai dan register peta yang diperlukan tersedia, GetScatterGatherList membuat daftar sebar/kumpulkan, menginisialisasi daftar peta, dan kemudian memanggil rutinitas AdapterListControl yang disediakan driver untuk melakukan operasi I/O.

GetScatterGatherList menggabungkan tindakan rutinitas AllocateAdapterChannel dan MapTransfer untuk driver yang melakukan DMA sebar/kumpulkan. GetScatterGatherList menentukan berapa banyak register peta yang diperlukan untuk transfer, mengalokasikan register peta, memetakan buffer untuk DMA, dan mengisi daftar sebar/kumpulkan. Kemudian memanggil rutinitas AdapterListControl yang disediakan, meneruskan pointer ke daftar sebar/kumpulkan di ScatterGather. Driver harus mempertahankan pointer ini untuk digunakan saat memanggil PutScatterGatherList. Perhatikan bahwa GetScatterGatherList tidak memiliki batasan antrean yang berlaku untuk AllocateAdapterChannel.

Dalam rutinitas AdapterListControl-nya , driver harus melakukan I/O. Saat kembali dari rutinitas yang disediakan driver, GetScatterGatherList menyimpan daftar peta tetapi membebaskan struktur adaptor DMA. Driver harus memanggil PutScatterGatherList (yang membersihkan buffer) sebelum dapat mengakses data di buffer.

Rutinitas ini dapat menangani MDL berantai, asalkan jumlah total register peta yang diperlukan oleh semua MDL berantai tidak melebihi jumlah register peta yang tersedia.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Windows 2000 dan versi Windows yang lebih baru. Tidak didukung di Windows 98 atau Windows Me.
Target Platform	Desktop
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL
Aturan kepatuhan DDI	IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)