Fungsi ExAllocatePoolWithTagPriority (wdm.h)
Rutinitas ExAllocatePoolWithTagPriority mengalokasikan memori kumpulan dari jenis yang ditentukan.
Peringatan
ExAllocatePoolWithTagPriority tidak digunakan lagi di Windows 10, versi 2004 dan telah digantikan oleh ExAllocatePool3. Untuk informasi selengkapnya, lihat Memperbarui panggilan ExAllocatePool yang tidak digunakan lagi ke ExAllocatePool2 dan ExAllocatePool3.
Sintaks
PVOID ExAllocatePoolWithTagPriority(
[in] __drv_strictTypeMatch(__drv_typeCond)POOL_TYPE PoolType,
[in] SIZE_T NumberOfBytes,
[in] ULONG Tag,
[in] __drv_strictTypeMatch(__drv_typeExpr)EX_POOL_PRIORITY Priority
);
Parameter
[in] PoolType
Jenis memori kumpulan yang akan dialokasikan. Untuk deskripsi jenis memori kumpulan yang tersedia, lihat POOL_TYPE.
Anda dapat mengubah nilai PoolType dengan bitwise-ORing nilai ini dengan bendera POOL_RAISE_IF_ALLOCATION_FAILURE. Bendera ini menyebabkan pengecualian dinaikkan jika permintaan tidak dapat dipenuhi.
Demikian pula, Anda dapat memodifikasi nilai PoolType dengan bitwise-ORing nilai ini dengan bendera POOL_COLD_ALLOCATION sebagai petunjuk kernel untuk mengalokasikan memori dari halaman yang kemungkinan akan di-page out dengan cepat. Untuk mengurangi jumlah memori kumpulan penduduk sebanyak mungkin, Anda tidak boleh sering mereferensikan alokasi ini. Bendera POOL_COLD_ALLOCATION hanya nasihat dan tersedia dimulai dengan Windows XP.
[in] NumberOfBytes
Jumlah byte yang akan dialokasikan.
[in] Tag
Tag kumpulan yang digunakan untuk memori yang dialokasikan. Untuk informasi selengkapnya, lihat parameter TagExAllocatePoolWithTag.
[in] Priority
Prioritas permintaan ini. Atur parameter ini ke salah satu nilai enumerasi EX_POOL_PRIORITY berikut.
| Nilai prioritas | Deskripsi |
|---|---|
| LowPoolPriority | Menentukan bahwa sistem mungkin gagal dalam permintaan ketika sumber daya hampir habis. Alokasi driver yang dapat pulih dari kegagalan alokasi menggunakan prioritas ini. |
| NormalPoolPriority | Menentukan bahwa sistem mungkin gagal permintaan ketika berjalan sangat rendah pada sumber daya. Sebagian besar driver harus menggunakan nilai ini. |
| HighPoolPriority | Menentukan bahwa sistem tidak boleh gagal dalam permintaan, kecuali jika benar-benar kehabisan sumber daya. Driver hanya menggunakan nilai ini ketika sangat penting agar permintaan berhasil. |
Enumerasi EX_POOL_PRIORITY mendefinisikan varian XxxSpecialPoolOverrun dan XxxSpecialPoolUnderrun untuk menentukan bagaimana memori harus dialokasikan ketika Driver Verifier (atau kumpulan khusus) diaktifkan. Jika driver menentukan XxxSpecialPoolUnderrun, ketika manajer memori mengalokasikan memori dari kumpulan khusus, ia mengalokasikannya di awal halaman fisik. Jika driver menentukan XxxSpecialPoolOverrun, manajer memori mengalokasikannya di akhir halaman fisik.
Mengembalikan nilai
ExAllocatePoolWithTagPriority mengembalikan NULL jika tidak ada cukup memori di kumpulan gratis untuk memenuhi permintaan kecuali POOL_RAISE_IF_ALLOCATION_FAILURE ditentukan. Jika tidak, rutinitas mengembalikan penunjuk ke memori yang dialokasikan.
Keterangan
Pemanggil ExAllocatePoolWithTagPriority harus dijalankan di IRQL <= DISPATCH_LEVEL. Penelepon yang dijalankan di DISPATCH_LEVEL harus menentukan nilai XxxNonPaged untuk PoolType. Penelepon yang mengeksekusi di IRQL <= APC_LEVEL dapat menentukan nilai POOL_TYPE apa pun, tetapi IRQL dan lingkungan juga harus dipertimbangkan untuk menentukan jenis halaman.
Jika NumberOfBytes PAGE_SIZE atau lebih besar, buffer yang diratakan halaman dialokasikan. Alokasi memori PAGE_SIZE atau kurang dialokasikan dalam halaman dan tidak melewati batas halaman. Alokasi memori kurang dari PAGE_SIZE belum tentu selaras dengan halaman tetapi selaras dengan batas 8-byte dalam sistem 32-bit dan ke batas 16-byte dalam sistem 64-bit.
Jangan atur NumberOfBytes = 0. Hindari alokasi panjang nol karena mereka membuang ruang header kumpulan dan, dalam banyak kasus, menunjukkan potensi masalah validasi dalam kode panggilan. Untuk alasan ini, Driver Verifier menandai alokasi tersebut sebagai kemungkinan kesalahan.
Sistem secara otomatis mengatur objek peristiwa standar tertentu ketika jumlah kumpulan (paged atau nonpaged) tinggi atau rendah. Driver dapat menunggu peristiwa ini untuk menyempurnakan penggunaan kumpulan mereka. Untuk informasi selengkapnya, lihat Objek Peristiwa Standar.
Dalam arsitektur multiprosesor akses memori non-seragam (NUMA), ExAllocatePoolWithTagPriority mencoba mengalokasikan memori yang bersifat lokal untuk prosesor yang memanggil ExAllocatePoolWithTagPriority. Jika tidak ada memori lokal yang tersedia, ExAllocatePoolWithTagPriority mengalokasikan memori terdekat yang tersedia.
Memori yang dialokasikan ExAllocatePoolWithTagPriority tidak diinisialisasi. Driver mode-kernel harus terlebih dahulu nol memori ini jika akan membuatnya terlihat oleh perangkat lunak mode pengguna (untuk menghindari bocornya konten yang berpotensi istimewa).
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Target Platform | Universal |
| Header | wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h) |
| Pustaka | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | IRQL <= DISPATCH_LEVEL (lihat bagian Keterangan) |
| Aturan kepatuhan DDI | HwStorPortProhibitedDDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree2(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm) |