PBUILD_SCATTER_GATHER_LIST_EX fungsi panggilan balik (wdm.h)

Artikel
03/08/2023

Rutinitas BuildScatterGatherListEx 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

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. 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

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	Makna
DMA_SYNCHRONOUS_CALLBACK	Rutinitas BuildScatterGatherListEx dipanggil 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, ExecutionRoutine bersifat opsional dan dapat berupa NULL. Jika ExecutionRoutine adalah NULL, pemanggil dapat menggunakan sumber daya yang dialokasikan oleh BuildScatterGatherListEx. 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] ScatterGatherBuffer

Penunjuk ke buffer yang dialokasikan penelepon 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 ScatterGatherBuffer . Ukuran buffer yang dialokasikan harus cukup besar untuk berisi daftar sebar/kumpulkan, ditambah data internal yang disimpan sistem operasi dalam buffer ini. Untuk menghitung ukuran buffer yang diperlukan, panggil rutinitas GetDmaTransferInfo atau CalculateScatterGatherList .

[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 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 ScatterGatherBuffer .

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 BuildScatterGatherListEx 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.

Mengembalikan nilai

BuildScatterGatherListEx 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_BUFFER_TOO_SMALL	Buffer yang disediakan penelepon di ScatterGatherBuffer terlalu kecil untuk berisi daftar sebar/kumpulkan.
STATUS_INSUFFICIENT_RESOURCES	Rutinitas gagal mengalokasikan sumber daya yang diperlukan untuk transfer DMA.

Keterangan

BuildScatterGatherListEx* 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 BuildScatterGatherListEx hanya untuk adaptor master bus. Jangan gunakan rutinitas ini untuk adaptor DMA sistem.

BuildScatterGatherListEx mirip dengan rutinitas GetScatterGatherListEx , kecuali mengharuskan pemanggil untuk mengalokasikan buffer untuk daftar sebar/kumpulkan.

Misalnya, driver mungkin melakukan pra-alokasi satu atau beberapa buffer sebar/kumpulkan selama inisialisasi perangkat. Kemudian, 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 rutinitas CancelAdapterChannel .

Jika driver panggilan mengatur bendera DMA_SYNCHRONOUS_CALLBACK , rutin 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 rutinitas AdapterListControl . 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 daftar sebar/kumpulkan setelah BuildScatterGatherListEx kembali. Dalam hal ini, driver harus menyediakan penunjuk ScatterGatherListnon-NULL yang valid. Selain itu, setelah transfer DMA yang dimulai driver selesai, driver harus memanggil rutinitas FreeAdapterObject untuk membebaskan sumber daya yang dialokasikan BuildScatterGatherListEx untuk objek adaptor.

BuildScatterGatherListEx adalah versi yang diperluas dari rutinitas BuildScatterGatherList . Daftar berikut ini merangkum fitur yang hanya tersedia dalam versi yang diperluas:

Fitur	Deskripsi
Memulai offset	Driver panggilan dapat menentukan offset awal untuk transfer DMA sebar/kumpulkan alih-alih memulai transfer di 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

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