PINITIALIZE_DMA_TRANSFER_CONTEXT fungsi panggilan balik (wdm.h)

Artikel
03/05/2024

Rutinitas InitializeDmaTransferContext menginisialisasi konteks transfer DMA buram yang digunakan untuk melacak alokasi sumber daya DMA yang tertunda.

Sintaks

PINITIALIZE_DMA_TRANSFER_CONTEXT PinitializeDmaTransferContext;

NTSTATUS PinitializeDmaTransferContext(
  [in]  PDMA_ADAPTER DmaAdapter,
  [out] PVOID DmaTransferContext
)
{...}

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 .

[out] DmaTransferContext

Penunjuk ke buffer yang dialokasikan pemanggil tempat InitializeDmaTransferContext menulis nilai awal untuk konteks transfer DMA. Konteks ini buram bagi pemanggil. Pemanggil harus mengalokasikan buffer yang cukup besar untuk berisi konteks transfer DMA. Ukuran, dalam byte, dari konteks ini ditentukan oleh konstanta DMA_TRANSFER_CONTEXT_SIZE_V1 dalam file header Wdm.h.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETERS	Rutinitas ini gagal karena nilai parameter yang tidak valid yang diteruskan oleh pemanggil.

Keterangan

InitializeDmaTransferContext 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 rutin ini dengan memanggil IoGetDmaAdapter dengan anggota Versi parameter DeviceDescription diatur ke DEVICE_DESCRIPTION_VERSION3. Jika IoGetDmaAdapter mengembalikan NULL, rutinitas tidak tersedia di platform Anda.

Konteks transfer DMA yang diinisialisasi harus disediakan sebagai parameter untuk rutinitas AllocateAdapterChannelEx, GetScatterGatherListEx, atau BuildScatterGatherListEx . Masing-masing rutinitas ini menulis informasi tentang alokasi sumber daya DMA yang diminta ke konteks transfer DMA. Informasi ini buram untuk pemanggil. Untuk membatalkan permintaan alokasi yang tertunda, pemanggil harus menyediakan konteks transfer DMA untuk permintaan ke rutinitas CancelAdapterChannel .

Konteks transfer DMA yang disediakan untuk AllocateAdapterChannelEx, GetScatterGatherListEx, atau BuildScatterGatherListEx harus unik di semua permintaan alokasi adapter.

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