Fungsi ExAllocatePoolWithTag (wdm.h)

Artikel
05/23/2024

Rutinitas ExAllocatePoolWithTag mengalokasikan memori kumpulan dari jenis yang ditentukan dan mengembalikan pointer ke blok yang dialokasikan.

Peringatan

ExAllocatePoolWithTag tidak digunakan lagi dalam Windows 10, versi 2004 dan telah digantikan oleh ExAllocatePool2. Untuk informasi selengkapnya, lihat Memperbarui panggilan ExAllocatePool yang tidak digunakan lagi ke ExAllocatePool2 dan ExAllocatePool3.

Sintaks

PVOID ExAllocatePoolWithTag(
  [in] __drv_strictTypeMatch(__drv_typeExpr)POOL_TYPE PoolType,
  [in] SIZE_T                                         NumberOfBytes,
  [in] ULONG                                          Tag
);

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. Penggunaan bendera POOL_RAISE_IF_ALLOCATION_FAILURE tidak disarankan karena mahal.

Demikian pula, Anda dapat memodifikasi nilai PoolType dengan bitwise-ORing nilai ini dengan bendera POOL_COLD_ALLOCATION sebagai petunjuk ke 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.

[in] NumberOfBytes

Jumlah byte yang akan dialokasikan.

[in] Tag

Tag kumpulan yang digunakan untuk memori yang dialokasikan. Tentukan tag kumpulan sebagai karakter bukan nol literal 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 pemverifikasi mengidentifikasi jalur kode.

Menampilkan nilai

ExAllocatePoolWithTag mengembalikan NULL jika memori di kumpulan gratis tidak cukup untuk memenuhi permintaan. Jika tidak, rutinitas mengembalikan pointer ke memori yang dialokasikan.

Keterangan

Rutinitas ini digunakan untuk alokasi kumpulan umum memori.

Jika NumberOfBytes PAGE_SIZE atau lebih besar, buffer yang selaras dengan 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.

Alokasi yang berhasil meminta NumberOfBytes< PAGE_SIZE kumpulan yang tidak di-halaman memberi pemanggil jumlah byte memori yang diminta. Jika permintaan alokasi untuk NumberOfBytes> PAGE_SIZE berhasil dan NumberOfBytes bukan kelipatan PAGE_SIZE yang tepat, halaman terakhir dalam alokasi berisi byte yang bukan bagian dari alokasi pemanggil. Jika memungkinkan, alokator kumpulan menggunakan byte ini. Untuk menghindari data rusak milik komponen mode kernel lainnya, driver hanya boleh mengakses alamat penyimpanan yang telah dialokasikan secara eksplisit.

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 termasuk dalam WDK, melacak memori berdasarkan tag kumpulan.

Nilai Tag disimpan, dan terkadang ditampilkan, dalam urutan terbalik (little-endian). Misalnya, jika penelepon meneruskan 'Fred' sebagai Tag, itu muncul sebagai "derF" di pool dump dan dalam pelacakan penggunaan kumpulan di debugger, dan sebagai 0x64657246 di registri dan di alat ditampilkan.

Buffer yang dialokasikan dapat dibebaskan dengan ExFreePool atau ExFreePoolWithTag.

Sistem secara otomatis menetapkan 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.

Pemanggil ExAllocatePoolWithTag harus dijalankan di IRQL <= DISPATCH_LEVEL. Penelepon yang mengeksekusi 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.

Jangan atur NumberOfBytes = 0. Hindari alokasi panjang nol karena ruang header kumpulan pemborosan dan, dalam banyak kasus, menunjukkan potensi masalah validasi dalam kode panggilan. Untuk alasan ini, Driver Verifier menandai alokasi tersebut sebagai kemungkinan kesalahan.

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

Memori yang dialokasikan ExAllocatePoolWithTag tidak diinisialisasi. Driver mode kernel harus terlebih dahulu nol memori ini jika akan membuatnya terlihat oleh perangkat lunak mode pengguna (untuk menghindari kebocoran 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	CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree1(wdm), PowerDownAllocate(wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm)