PBUILD_SCATTER_GATHER_LIST fungsi panggilan balik (wdm.h)

Artikel
02/27/2024

Rutinitas BuildScatterGatherList menyiapkan sistem untuk operasi DMA, menggunakan buffer yang disediakan driver untuk membangun daftar sebar/kumpulkan.

Sintaks

PBUILD_SCATTER_GATHER_LIST PbuildScatterGatherList;

NTSTATUS PbuildScatterGatherList(
  [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,
  [in] PVOID ScatterGatherBuffer,
  [in] ULONG ScatterGatherLength
)
{...}

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

Penunjuk ke MDL yang menjelaskan buffer yang ditentukan oleh anggota MdlAddress dari 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, dari buffer yang akan dipetakan.

[in] ExecutionRoutine

Penunjuk ke rutinitas AdapterListControl yang disediakan driver, yang disebut di IRQL = DISPATCH_LEVEL ketika pengontrol DMA sistem atau adaptor bus-master tersedia.

[in] Context

Arahkan ke konteks yang ditentukan driver yang diteruskan ke ExecutionRoutine saat dipanggil.

[in] WriteToDevice

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

[in] ScatterGatherBuffer

Arahkan ke buffer yang disediakan pemanggil yang diisi rutinitas dengan struktur SCATTER_GATHER_LIST .

[in] ScatterGatherLength

Menentukan ukuran, dalam byte, dari buffer yang diteruskan dalam parameter ScatterGatherBuffer .

Nilai kembali

BuildScatterGatherList mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Operasi berhasil diselesaikan.
STATUS_INSUFFICIENT_RESOURCES	Sistem tidak memiliki cukup register peta yang tersedia untuk transfer.
STATUS_BUFFER_TOO_SMALL	Panjang yang ditentukan terlalu besar agar pas di dalam buffer.

Keterangan

BuildScatterGatherList 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_VERSION2. Jika IoGetDmaAdapter mengembalikan NULL, rutinitas tidak tersedia di platform Anda.

BuildScatterGatherList melakukan operasi yang sama dengan GetScatterGatherList, kecuali bahwa ia menggunakan buffer yang disediakan dalam parameter ScatterGatherBuffer untuk menyimpan daftar sebar/kumpulkan yang dibuatnya. Sebaliknya, GetScatterGatherList secara dinamis mengalokasikan buffer untuk menahan daftar sebar/kumpulkan. Jika memori tidak cukup tersedia untuk mengalokasikan buffer, GetScatterGatherList dapat gagal dengan kesalahan STATUS_INSUFFICIENT_RESOURCES. Driver yang harus menghindari skenario ini dapat melakukan pra-alokasi buffer untuk menahan daftar sebar/kumpulkan, dan menggunakan BuildScatterGatherList sebagai gantinya.

Driver dapat menggunakan rutinitas CalculateScatterGatherList untuk menentukan ukuran buffer yang akan dialokasikan untuk menahan daftar sebar/kumpulkan.

Driver harus mempertahankan penunjuk ke daftar sebar/kumpulkan di ScatterGatherBuffer untuk digunakan ketika driver memanggil PutScatterGatherList. Driver harus memanggil PutScatterGatherList (yang menghapus daftar) sebelum dapat mengakses data dalam daftar.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Windows XP dan versi Windows yang lebih baru.
Target Platform	Desktop
Header	wdm.h (termasuk Wdm.h)
IRQL	DISPATCH_LEVEL
Aturan kepatuhan DDI	IrqlDispatch(wdm)