PALLOCATE_ADAPTER_CHANNEL_EX fungsi panggilan balik (wdm.h)

Artikel
03/08/2023

Rutinitas AllocateAdapterChannelEx mengalokasikan sumber daya yang diperlukan untuk melakukan transfer DMA, dan kemudian memanggil rutinitas AdapterControl yang disediakan driver untuk memulai transfer DMA.

Sintaks

PALLOCATE_ADAPTER_CHANNEL_EX PallocateAdapterChannelEx;

NTSTATUS PallocateAdapterChannelEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            ULONG NumberOfMapRegisters,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_CONTROL ExecutionRoutine,
  [in, optional]  PVOID ExecutionContext,
  [out, optional] PVOID *MapRegisterBase
)
{...}

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] NumberOfMapRegisters

Jumlah register peta yang akan digunakan dalam transfer DMA. Driver panggilan harus mengatur nilai ini ke lebih sedikit dari jumlah register peta yang diperlukan untuk memenuhi permintaan transfer saat ini, dan jumlah register peta yang tersedia. Driver sebelumnya disebut rutin GetDmaTransferInfo untuk mendapatkan jumlah register peta yang diperlukan untuk transfer, dan memanggil rutinitas IoGetDmaAdapter untuk mendapatkan jumlah register peta yang tersedia.

[in] Flags

Bendera alokasi saluran adaptor. Bendera berikut didukung.

Bendera	Makna
DMA_SYNCHRONOUS_CALLBACK	Rutinitas AllocateAdapterChannelEx 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. Untuk informasi selengkapnya tentang bendera ini, lihat bagian Keterangan.

[in, optional] ExecutionRoutine

Penunjuk ke rutinitas AdapterControl yang disediakan driver yang memulai transfer DMA untuk driver. Manajer I/O memanggil rutinitas AdapterControl setelah sumber daya yang diperlukan dialokasikan untuk objek adaptor. Setelah rutinitas AdapterControl kembali, manajer I/O secara otomatis membebaskan objek adaptor. Manajer I/O juga dapat membebaskan sumber daya yang dialokasikan untuk objek ini, tergantung pada nilai yang dikembalikan oleh rutinitas ini.

Jika bendera DMA_SYNCHRONOUS_CALLBACK diatur, ExecutionRoutine bersifat opsional dan dapat berupa NULL. Dalam hal ini, pemanggil dapat menggunakan sumber daya yang dialokasikan oleh AllocateAdapterChannelEx, dan kemudian membebaskan sumber daya ini dengan memanggil rutinitas FreeAdapterObject . Untuk informasi lebih lanjut, lihat bagian Keterangan.

[in, optional] ExecutionContext

Konteks kontrol adaptor yang ditentukan driver. Konteks ini diteruskan ke rutinitas AdapterControl sebagai parameter Konteks .

[out, optional] MapRegisterBase

Penunjuk ke variabel tempat rutin menulis handel ke daftar peta yang dialokasikan. Pemanggil dapat menyediakan handel ini sebagai parameter ke Rutinitas FlushAdapterBuffersEx, FlushAdapterBuffers, FreeMapRegisters, atau MapTransferEx .

Jika bendera DMA_SYNCHRONOUS_CALLBACK diatur, MapRegisterBase harus merupakan penunjuk non-NULL yang valid. Jika parameter ExecutionRoutine bukan NULL, MapRegisterBase harus NULL. Panggilan gagal jika MapRegisterBase bukan NULL dan bendera DMA_SYNCHRONOUS_CALLBACK tidak diatur, atau jika MapRegisterBase dan ExecutionRoutine keduanya NULL.

Nilai kembali

AllocateAdapterChannelEx 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_INSUFFICIENT_RESOURCES	Rutinitas gagal mengalokasikan sumber daya yang diperlukan untuk transfer DMA.

Keterangan

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

AllocateAdapterChannelEx mengalokasikan sumber daya yang diperlukan untuk melakukan operasi DMA. Sumber daya ini termasuk saluran DMA dan register peta. Setelah semua sumber daya yang diperlukan dialokasikan untuk digunakan oleh adaptor DMA, AllocateAdapterChannelEx memanggil rutinitas AdapterControl yang disediakan pemanggil untuk memulai operasi DMA.

Secara default, AllocateAdapterChannelEx 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 AllocateAdapterChannelEx berperilaku sebagai berikut:

Jika sumber daya DMA yang diminta tidak segera tersedia, AllocateAdapterChannelEx tidak menunggu sumber daya dan tidak memanggil rutinitas AdapterControl . Sebaliknya, AllocateAdapterChannelEx gagal dan mengembalikan STATUS_INSUFFICIENT_RESOURCES.
Driver tidak diperlukan untuk menyediakan rutinitas AdapterControl jika bendera DMA_SYNCHRONOUS_CALLBACK diatur.
Jika driver menyediakan rutinitas AdapterControl , bendera DMA_SYNCHRONOUS_CALLBACK menunjukkan bahwa rutinitas ini akan dipanggil dalam konteks utas panggilan, sebelum AllocateAdapterChannelEx kembali.
Jika driver tidak menyediakan rutinitas AdapterControl , driver dapat menggunakan sumber daya yang dialokasikan setelah AllocateAdapterChannelEx kembali. Dalam hal ini, driver harus memanggil FreeAdapterObject setelah selesai menggunakan sumber daya yang dialokasikan.

AllocateAdapterChannelEx adalah versi yang diperluas dari rutinitas AllocateAdapterChannel . Fitur berikut hanya tersedia dalam versi yang diperluas:

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