Fungsi ExAllocatePool2 (wdm.h)

  • Artikel

Rutinitas ExAllocatePool2 mengalokasikan memori kumpulan dari jenis yang ditentukan dan mengembalikan penunjuk ke blok yang dialokasikan.

Sintaks

DECLSPEC_RESTRICT PVOID ExAllocatePool2(
  POOL_FLAGS Flags,
  SIZE_T     NumberOfBytes,
  ULONG      Tag
);

Parameter

Flags

Nilai jenis ULONG64 yang menentukan jenis memori kumpulan bersama dengan atribut yang diperlukan dan opsional. Beberapa nilai bendera dapat digabungkan menggunakan bit-wise OR. Lihat POOL_FLAGS untuk nilai yang mungkin.

NumberOfBytes

Menentukan jumlah byte bukan nol untuk dialokasikan.

Tag

Tag kumpulan yang digunakan untuk memori yang dialokasikan. Tentukan tag kumpulan sebagai literal karakter bukan nol dari satu hingga empat karakter yang dibatasi oleh tanda kutip tunggal (misalnya, Tag1). String biasanya ditentukan dalam urutan terbalik (misalnya, 1gaT). Setiap karakter ASCII dalam tag harus berupa nilai dalam rentang 0x20 (spasi) hingga 0x7E (tilde). Setiap jalur kode alokasi harus menggunakan tag kumpulan unik untuk membantu debugger dan verifier mengidentifikasi jalur kode.

Mengembalikan nilai

ExAllocatePool2 mengembalikan pointer ke memori yang dialokasikan.

Kondisi berikut menyebabkan fungsi mengembalikan NULL secara default. Jika POOL_FLAG_RAISE_ON_FAILURE ditentukan, fungsi akan menimbulkan pengecualian.

  • Memori tidak mencukuum
  • Tag diatur ke 0 atau POOL_FLAGS tidak valid ditentukan

Keterangan

Jika Anda membangun driver yang menargetkan versi Windows sebelum Windows 10, versi 2004, gunakan ExAllocatePoolZero, ExAllocatePoolUninitialized, ExAllocatePoolQuotaZero, atau ExAllocatePoolQuotaUninitialized.

Rutinitas ini memiliki perbedaan berikut dari rutinitas alokasi sebelumnya (ExAllocatePoolWithTag, ExAllocatePoolWithQuotaTag, ExAllocatePoolWithTagPriority):

  1. Memori tidak diinisialisasi kecuali POOL_FLAG_UNINITIALIZED ditentukan.

  2. Mengembalikan perilaku jika terjadi alokasi yang gagal. ExAllocatePoolWithQuotaTag menimbulkan pengecualian secara default.

  3. Tag dengan nilai 0 tidak valid.

Saat mengganti ExAllocatePoolWithQuotaTag dengan ExAllocatePool2, Anda harus menentukan bendera POOL_FLAG_USE_QUOTA . Untuk informasi selengkapnya tentang bendera kumpulan, lihat POOL_FLAGS.

Jika NumberOfBytes atau PAGE_SIZE lebih besar, buffer sejajar halaman dialokasikan. Alokasi PAGE_SIZE memori atau kurang dialokasikan dalam halaman dan tidak melewati batas halaman. Alokasi memori kurang dari PAGE_SIZE yang belum tentu selaras dengan halaman tetapi selaras dengan batas 8-byte dalam sistem 32-bit dan ke batas 16-byte dalam sistem 64-bit.

Driver hanya dapat menggunakan hingga NumberOfBytes yang telah dialokasikan secara eksplisit. Mengakses memori di luar rentang ini dapat merusak kumpulan dan menyebabkan sistem lumpuh.

Sistem mengaitkan tag kumpulan dengan memori yang dialokasikan. Alat pemrograman, seperti WinDbg, dapat menampilkan tag kumpulan yang terkait dengan setiap buffer yang dialokasikan. Gflags, alat yang disertakan dalam Alat Debugging untuk Windows, mengaktifkan fitur sistem yang meminta alokasi dari kumpulan khusus untuk tag kumpulan tertentu. Poolmon, yang disertakan dalam WDK, melacak memori menurut tag kumpulan.

Nilai Tag disimpan, dan terkadang ditampilkan, dalam urutan terbalik (little-endian). Misalnya, jika penelepon lolos Fred sebagai Tag, pemanggil muncul seperti derF di cadangan kumpulan dan di pelacakan penggunaan kumpulan di debugger, dan seperti 0x64657246 dalam registri dan di alat ditampilkan.

Buffer yang dialokasikan dapat dikosongkan dengan ExFreePool atau ExFreePoolWithTag.

Penelepon ExAllocatePool2 harus berjalan di IRQL <= DISPATCH_LEVEL. Penelepon yang dijalankan di DISPATCH_LEVEL harus menentukan POOL_FLAG_NON_PAGED atau POOL_FLAG_NON_PAGED_EXECUTABLE untuk Bendera. Penelepon yang mengeksekusi di IRQL <= APC_LEVEL dapat menentukan POOL_FLAG_PAGED, tetapi jika memori akan diakses dari kode yang berjalan pada DISPATCH_LEVEL, Anda masih harus mengalokasikan memori non-halaman.

Dalam arsitektur multiprosesor akses memori non-seragam (NUMA), ExAllocatePool2 mencoba mengalokasikan memori yang bersifat lokal untuk prosesor yang memanggil ExAllocatePool2. Jika tidak ada memori lokal yang tersedia, ExAllocatePool2 mengalokasikan memori terdekat yang tersedia.

Memori yang dialokasikan ExAllocatePool2 adalah nol yang diinisialisasi. Driver mode kernel tidak boleh menolak nol untuk alokasi yang akan disalin ke lokasi yang tidak tepercaya (mode pengguna, melalui jaringan, dll.) untuk menghindari pengungkapan informasi sensitif.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows 10, version 2004
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, SpNoWait, StorPortStartIo

Lihat juga

ExAllocatePool3