PINITIALIZE_DMA_TRANSFER_CONTEXT fungsi panggilan balik (wdm.h)

Artikel
07/02/2025

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

Sintaksis

C++

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

Mengembalikan nilai

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

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

Komentar

InitializeDmaTransferContext bukanlah rutinitas sistem yang dapat dipanggil langsung berdasarkan nama. Rutinitas ini hanya dapat dipanggil oleh pointer 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.

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

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

Persyaratan

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