Fungsi IoGetDmaAdapter (wdm.h)
Rutinitas IoGetDmaAdapter mengembalikan penunjuk ke struktur adaptor DMA untuk objek perangkat fisik.
Sintaks
_DMA_ADAPTER * IoGetDmaAdapter(
[in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
[in] _DEVICE_DESCRIPTION *DeviceDescription,
[out] PULONG NumberOfMapRegisters
);
Parameter
[in, optional] PhysicalDeviceObject
Arahkan ke objek perangkat fisik untuk perangkat yang meminta struktur adaptor DMA.
[in] DeviceDescription
Arahkan ke struktur DEVICE_DESCRIPTION , yang menjelaskan atribut perangkat fisik. Terlepas dari versi yang ditetapkan dalam struktur DEVICE_DESCRIPTION, fungsi ini selalu mengembalikan DMA_ADAPTER->Version == 1.
[out] NumberOfMapRegisters
Pointer ke, pada output, jumlah maksimum register peta yang dapat dialokasikan driver untuk setiap operasi transfer DMA.
Nilai kembali
IoGetDmaAdapter mengembalikan penunjuk ke struktur DMA_ADAPTER , yang berisi pointer ke fungsi yang mendukung operasi DMA yang ditentukan sistem. Jika struktur tidak dapat dialokasikan, rutinitas mengembalikan NULL. Lihat komentar versi di atas dalam deskripsi parameter DeviceDescription .
Keterangan
Sebelum memanggil rutinitas ini, driver harus menginisialisasi nol struktur DEVICE_DESCRIPTION yang diarahkan oleh DeviceDescription lalu menambahkan informasi yang relevan untuk perangkatnya ke struktur ini.
Jika berhasil, nilai yang dikembalikan rutin menunjuk ke struktur DMA_ADAPTER . Struktur ini berisi penunjuk ke struktur DMA_OPERATIONS , yang merupakan tabel penunjuk ke fungsi yang kemudian dapat digunakan driver untuk melakukan operasi DMA. Versi struktur ini yang dikembalikan rutin ditentukan sebagai berikut:
Jika driver mengatur anggota Versi struktur DEVICE_DESCRIPTION ke DEVICE_DESCRIPTION_VERSION atau DEVICE_DESCRIPTION_VERSION1, struktur DMA_ADAPTER yang dikembalikan menunjuk ke versi 1 dari struktur DMA_OPERATIONS .
Jika driver mengatur Versi = DEVICE_DESCRIPTION_VERSION2, struktur DMA_ADAPTER yang dikembalikan menunjuk ke versi 2 dari struktur DMA_OPERATIONS jika versi 2 didukung; jika tidak, rutinitas mengembalikan NULL. Driver harus memeriksa untuk melihat apakah versi 2 didukung sebelum mencoba menggunakan fungsi versi 2 apa pun.
Jika driver mengatur Versi = DEVICE_DESCRIPTION_VERSION3, struktur DMA_ADAPTER yang dikembalikan menunjuk ke versi 3 dari struktur DMA_OPERATIONS jika versi 3 didukung; jika tidak, rutinitas mengembalikan NULL. Driver harus memeriksa untuk melihat apakah versi 3 didukung sebelum mencoba menggunakan fungsi versi 3 apa pun. Versi 3 didukung dimulai dengan Windows 8.
Driver PnP memanggil IoGetDmaAdapter ketika rutinitas AddDevice-nya dipanggil atau ketika menangani permintaan PnP IRP_MN_START_DEVICE untuk perangkat. IRP ini mencakup informasi tentang sumber daya perangkat keras perangkat yang harus disediakan driver dalam struktur DeviceDescription .
Pemanggil menggunakan anggota MaximumLength dalam struktur DeviceDescription untuk menunjukkan jumlah register peta yang optimal yang dapat digunakannya. Manajer I/O akan mencoba mengalokasikan register peta yang cukup untuk mengakomodasi operasi transfer DMA dengan ukuran maksimum ini. Pada output, manajer I/O mengembalikan, dalam parameter NumberOfMapRegisters , jumlah register peta yang dialokasikannya. Driver harus memeriksa nilai yang dikembalikan; tidak ada jaminan driver akan menerima jumlah register peta yang sama dengan yang dimintanya.
Untuk membebaskan objek adaptor, driver harus memanggil PutDmaAdapter melalui pointer yang dikembalikan dalam struktur DMA_ADAPTER .
Seperti yang dijelaskan sebelumnya, IoGetDmaAdapter mengembalikan NULL jika tidak mendukung versi struktur DMA_ADAPTER yang ditentukan oleh DeviceDescription-Version>. Penelepon harus mengandalkan perilaku ini untuk menentukan apakah rutinitas mengembalikan penunjuk ke versi struktur DMA_ADAPTER yang diminta. Saat IoGetDmaAdapter mengembalikan penunjuk ke versi 1 atau versi 2 atau versi 3 dari struktur DMA_ADAPTER , anggota Versi struktur ini selalu diatur ke 1. Dengan demikian, pemanggil tidak dapat menggunakan anggota Versi dari struktur DMA_ADAPTER yang dikembalikan untuk membedakan antara versi 1, 2 dan 3 dari struktur ini.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Target Platform | Universal |
| Header | wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h) |
| Pustaka | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Aturan kepatuhan DDI | HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm) |