PALLOCATE_COMMON_BUFFER fungsi panggilan balik (wdm.h)

Artikel
08/08/2023

Rutinitas AllocateCommonBuffer mengalokasikan memori dan memetakannya sehingga dapat diakses secara bersamaan dari prosesor dan perangkat untuk operasi DMA.

Sintaks

PALLOCATE_COMMON_BUFFER PallocateCommonBuffer;

PVOID PallocateCommonBuffer(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  ULONG Length,
  [out] PPHYSICAL_ADDRESS LogicalAddress,
  [in]  BOOLEAN CacheEnabled
)
{...}

Parameter

[in] DmaAdapter

Penunjuk ke struktur DMA_ADAPTER yang dikembalikan oleh IoGetDmaAdapter yang mewakili adaptor bus-master atau pengontrol DMA.

[in] Length

Menentukan jumlah byte memori yang akan dialokasikan.

[out] LogicalAddress

Penunjuk ke variabel yang menerima alamat logis yang dapat digunakan perangkat untuk mengakses buffer yang dialokasikan. Gunakan alamat ini daripada memanggil MmGetPhysicalAddress karena sistem dapat memperhitungkan pembatasan memori khusus platform apa pun.

[in] CacheEnabled

Menentukan apakah memori yang dialokasikan dapat di-cache.

Parameter diabaikan Sistem operasi menentukan apakah akan mengaktifkan memori cache di buffer umum yang akan dialokasikan. Keputusan itu didasarkan pada arsitektur prosesor dan bus perangkat.

Pada komputer dengan prosesor berbasis x86, berbasis x64, dan berbasis Itanium, memori cache diaktifkan. Diasumsikan bahwa semua operasi DMA yang dilakukan oleh perangkat berkoheren dengan cache CPU yang relevan, yang mungkin membuat cache memori tersebut. Jika driver Anda perlu menonaktifkan penembolokan, panggil AllocateCommonBufferEx sebagai gantinya.

Pada komputer dengan prosesor berbasis ARM atau ARM 64, sistem operasi tidak secara otomatis mengaktifkan memori cache untuk semua perangkat. Sistem bergantung pada metode ACPI_CCA untuk setiap perangkat untuk menentukan apakah perangkat berkoheren cache.

Nilai kembali

AllocateCommonBuffer mengembalikan alamat virtual dasar dari rentang yang dialokasikan. Jika buffer tidak dapat dialokasikan, buffer mengembalikan NULL.

Keterangan

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

AllocateCommonBuffer mendukung DMA di mana perangkat dan prosesor terus berkomunikasi melalui memori sistem, seperti dalam struktur kontrol untuk perangkat DMA master bus.

AllocateCommonBuffer juga mendukung perangkat subordinat yang drivernya menggunakan mode autoinisialisasi pengontrol DMA sistem.

AllocateCommonBuffer melakukan hal berikut:

Mengalokasikan memori yang dapat dicapai dari prosesor dan perangkat. Memori ini tampak berseberangan dengan perangkat.
Mengalokasikan register peta untuk memetakan buffer, jika diperlukan oleh sistem.
Menyiapkan terjemahan untuk perangkat, termasuk memuat register peta jika perlu.

Untuk menggunakan memori sistem residen secara ekonomis, driver harus mengalokasikan sebanyak mungkin buffer ini per perangkat. AllocateCommonBuffer mengalokasikan setidaknya satu halaman memori, terlepas dari Panjang yang diminta. Setelah alokasi berhasil meminta kurang dari PAGE_SIZE byte, pemanggil hanya dapat mengakses Panjang yang diminta. Setelah alokasi berhasil meminta lebih dari kelipatan integral PAGE_SIZE byte, byte yang tersisa pada halaman terakhir yang dialokasikan tidak dapat diakses oleh pemanggil.

Jika driver membutuhkan beberapa halaman ruang buffer umum, tetapi halaman tidak perlu berdampingan, driver harus membuat beberapa permintaan satu halaman ke AllocateCommonBuffer alih-alih satu permintaan besar. Pendekatan ini menghemat memori yang berdekatan.

Driver biasanya memanggil AllocateCommonBuffer sebagai bagian dari start-up perangkat, selama respons mereka terhadap permintaan PnP IRP_MN_START_DEVICE . Setelah startup, ada kemungkinan bahwa hanya permintaan satu halaman yang akan berhasil, jika ada.

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	PASSIVE_LEVEL
Aturan kepatuhan DDI	IrqlDispatch(wdm)

Lihat juga