PALLOCATE_ADAPTER_CHANNEL fungsi panggilan balik (wdm.h)

Artikel
02/27/2024

Rutinitas AllocateAdapterChannel menyiapkan sistem untuk operasi DMA atas nama objek perangkat target, dan kemudian memanggil rutinitas AdapterControl yang disediakan driver untuk melakukan operasi DMA.

Sintaks

PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;

NTSTATUS PallocateAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] ULONG NumberOfMapRegisters,
  [in] PDRIVER_CONTROL ExecutionRoutine,
  [in] PVOID Context
)
{...}

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

[in] NumberOfMapRegisters

Menentukan jumlah register peta yang akan digunakan dalam transfer. Nilai ini adalah lebih sedikit dari jumlah register peta yang diperlukan untuk memenuhi permintaan transfer saat ini, dan jumlah register peta yang tersedia yang dikembalikan oleh IoGetDmaAdapter.

[in] ExecutionRoutine

Penunjuk ke rutinitas AdapterControl yang disediakan driver. Rutinitas dipanggil ketika pengontrol DMA sistem atau adaptor bus-master tersedia.

[in] Context

Arahkan ke konteks yang ditentukan driver untuk diteruskan ke rutinitas AdapterControl .

Nilai kembali

Rutinitas ini dapat mengembalikan salah satu nilai NTSTATUS berikut.

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Saluran adaptor telah dialokasikan. Sistem akan memanggil rutinitas AdapterControl setelah operasi DMA dapat dimulai.
STATUS_INSUFFICIENT_RESOURCES	NumberOfMapRegisters lebih besar dari nilai yang dikembalikan oleh IoGetDmaAdapter. Rutinitas AdapterControl tidak akan dipanggil.

Keterangan

AllocateAdapterChannel bukanlah rutinitas sistem yang dapat dipanggil langsung berdasarkan nama. Rutinitas ini hanya dapat dipanggil oleh penunjuk dari alamat yang dikembalikan dalam struktur DMA_OPERATIONS . Driver mendapatkan alamat rutinitas ini dengan memanggil IoGetDmaAdapter.

Driver memanggil rutinitas AllocateAdapterControl untuk mendaftarkan rutinitas AdapterControl yang melakukan operasi DMA untuk driver. Rutinitas AdapterControl melakukan operasi DMA menggunakan pengontrol DMA sistem atau adaptor master bus.

Jika operasi DMA dapat segera dilakukan, sistem segera memanggil AdapterControl. Jika pengontrol DMA sistem atau adaptor bus-master sedang digunakan, AllocateAdapterChannel mengantre AdapterControl hingga adaptor tersedia. Dalam kedua kasus, AllocateAdapterChannel mengembalikan STATUS_SUCCESS.

Jika sistem tidak memiliki sumber daya untuk melakukan operasi DMA, AllocateAdapterChannel mengembalikan STATUS_INSUFFICIENT_RESOURCES. Dalam hal ini, AdapterControl tidak diantrekan, dan driver harus menyelesaikan IRP saat ini dengan kode kesalahan yang sesuai (seperti STATUS_INSUFFICIENT_RESOURCES).

Rutinitas ini mencadangkan akses eksklusif ke saluran pengontrol DMA dan daftar peta untuk satu atau beberapa operasi DMA yang diperlukan untuk memenuhi permintaan transfer IRP saat ini untuk perangkat yang ditentukan.

Hanya satu permintaan DMA yang dapat diantrekan untuk objek perangkat kapan saja. Oleh karena itu, driver tidak boleh memanggil AllocateAdapterChannel lagi untuk operasi DMA lain pada objek perangkat yang sama sampai rutinitas AdapterControl selesai dieksekusi. Selain itu, driver tidak boleh memanggil AllocateAdapterChannel dari dalam rutinitas AdapterControl-nya .

Sistem meneruskan nilai anggota CurrentIrp dari DeviceObject sebagai parameter IrpAdapterControl. Jika AllocateAdapterChannel dipanggil dari rutinitas StartIo driver, ini dijamin akan menunjuk ke IRP bahwa StartIo dipanggil untuk diproses. Jika tidak, untuk menggunakan parameter IrpAdapterControl, driver harus mengatur CurrentIrp untuk menunjuk ke IRP saat ini sebelum memanggil AllocateAdapterChannel.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 2000.
Target Platform	Desktop
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL
Aturan kepatuhan DDI	IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)