Fungsi ExInitializePagedLookasideList (wdm.h)

Artikel
03/08/2023

Rutinitas ExInitializePagedLookasideList menginisialisasi daftar lookaside untuk entri yang dapat dipaginasi dari ukuran yang ditentukan.

Sintaks

void ExInitializePagedLookasideList(
  [out]          PPAGED_LOOKASIDE_LIST Lookaside,
  [in, optional] PALLOCATE_FUNCTION    Allocate,
  [in, optional] PFREE_FUNCTION        Free,
  [in]           ULONG                 Flags,
  [in]           SIZE_T                Size,
  [in]           ULONG                 Tag,
  [in]           USHORT                Depth
);

Parameter

[out] Lookaside

Penunjuk ke struktur PAGED_LOOKASIDE_LIST untuk diinisialisasi. Pemanggil harus menggunakan ruang sistem non-halaman untuk struktur, meskipun entri dalam daftar tampilan ini akan dialokasikan dari memori yang dapat di-pageable. Pada platform 64-bit, struktur ini harus selaras 16 byte.

[in, optional] Allocate

Penunjuk ke fungsi yang disediakan penelepon untuk mengalokasikan entri saat daftar lookaside kosong, atau ke NULL. Jika non-NULL, penunjuk adalah ke fungsi dengan prototipe:

PVOID XxxAllocate(
  __in POOL_TYPE  PoolType,           // PagedPool 
  __in SIZE_T  NumberOfBytes,         // value of Size
  __in ULONG  Tag                     // value of Tag
);

Jika parameter Alokasikan adalah NULL, panggilan berikutnya ke ExAllocateFromPagedLookasideList secara otomatis mengalokasikan entri setiap kali daftar lookaside kosong.

[in, optional] Free

Penunjuk ke fungsi yang disediakan penelepon untuk membebaskan entri setiap kali daftar lookaside penuh, atau ke NULL. Jika non-NULL, penunjuk adalah ke fungsi dengan prototipe:

VOID XxxFree(
  __in PVOID  Buffer
);

Jika parameter Gratisadalah NULL, panggilan berikutnya ke ExFreeToPagedLookasideList secara otomatis merilis entri yang diberikan kembali ke kumpulan halaman setiap kali daftar penuh, yaitu, saat ini memegang jumlah entri maksimum yang ditentukan sistem.

[in] Flags

Mulai dari Windows 8, parameter ini menentukan nilai bendera opsional untuk memodifikasi perilaku default rutinitas ExInitializePagedLookasideList. Bit bendera yang kompatibel mencakup yang berikut ini.

Bit bendera	Makna
POOL_RAISE_IF_ALLOCATION_FAILURE	Jika alokasi gagal, ajukan pengecualian.

Menentukan bendera POOL_NX_ALLOCATION tidak berpengaruh. Semua memori yang dapat di-pageable dialokasikan sebagai NX.

Sebelum Windows 8, parameter ini tidak digunakan dan harus nol.

[in] Size

Menentukan ukuran dalam byte dari setiap entri dalam daftar lookaside.

[in] Tag

Menentukan tag kumpulan yang akan digunakan saat mengalokasikan entri daftar lookaside. Untuk informasi selengkapnya tentang tag kumpulan, lihat Parameter tagExAllocatePoolWithTag.

[in] Depth

Dicadangkan. Harus nol.

Mengembalikan nilai

Tidak ada

Keterangan

Setelah memanggil ExInitializePagedLookasideList, blok Ukuran yang ditentukan pemanggil dapat dialokasikan dari dan dibebaskan ke daftar lookaside dengan panggilan ke ExAllocateFromPagedLookasideList dan ExFreeToPagedLookasideList, masing-masing. Entri yang dialokasikan dan dikosongkan secara dinamis dapat berupa struktur data atau buffer ukuran tetap yang digunakan pemanggil saat sistem berjalan, terutama jika pemanggil tidak dapat menentukan berapa banyak entri tersebut yang akan digunakan pada saat tertentu. Tata letak dan konten setiap entri ukuran tetap ditentukan pemanggil.

ExInitializePagedLookasideList menginisialisasi status sistem untuk melacak penggunaan daftar lookaside yang diberikan, sebagai berikut:

Menginisialisasi penghitung yang akan dipertahankan untuk entri.
Menyimpan titik masuk rutin XxxAllocate dan XxxFree yang disediakan pemanggil, jika ada, atau menetapkan titik masuk ini ke ExAllocatePoolWithTag dan ExFreePool.
Menginisialisasi kunci putar sistem untuk mengontrol alokasi dari dan membebaskan ke daftar lookaside dengan cara multiproscessor-aman jika perlu.
Menyimpan entri yang disediakan penelepon Ukuran dan daftar Tag.
Menyiapkan batas yang ditentukan sistem (minimum dan maksimum) pada jumlah entri yang akan ditahan dalam daftar tampilan, yang kemudian dapat disesuaikan jika permintaan seluruh sistem untuk entri lebih tinggi atau lebih rendah dari yang diantisipasi.
Menyiapkan bendera yang ditentukan sistem, yang mengontrol jenis memori tempat entri akan dialokasikan kemudian.

Sistem mempertahankan sekumpulan semua daftar lookaside yang digunakan. Karena permintaan untuk entri daftar lookaside dan pada memori halaman yang tersedia bervariasi saat sistem berjalan, sistem menyesuaikan batasnya untuk jumlah entri yang akan ditahan di setiap daftar tampilan halaman secara dinamis.

Driver harus selalu menggunakan secara eksplisit membebaskan daftar tampilan apa pun yang mereka buat sebelum membongkar. Untuk melakukan sebaliknya adalah kesalahan pemrograman yang serius. Gunakan ExDeletePagedLookasideList untuk membebaskan daftar.

ExInitializePagedLookasideList menyiapkan kepala daftar buram di lokasi yang disediakan pemanggil tetapi tidak mengalokasikan memori untuk entri daftar. Selanjutnya, entri awal dialokasikan secara dinamis sebagai panggilan ke ExAllocateFromPagedLookasideList terjadi, dan entri awal ini disimpan dalam daftar lookaside sebagai panggilan timbal balik ke ExFreeToPagedLookasideList terjadi. Entri dikumpulkan dalam daftar lookaside yang diberikan sampai maksimum yang ditentukan sistem tercapai, di mana entri tambahan dikembalikan ke kumpulan halaman saat dikosongkan. Jika daftar menjadi kosong, alokasikan permintaan dipenuhi oleh fungsi Alokasi Xxx yang ditentukan pada inisialisasi daftar atau oleh ExAllocatePoolWithTag.

Lebih efisien untuk meneruskan pointer NULL untuk parameter Alokasi dan GratisExInitializePagedLookasideList setiap kali pengguna daftar lookaside tidak lebih dari mengalokasikan dan merilis entri ukuran tetap. Namun, komponen apa pun yang menggunakan daftar tampilan mungkin menyediakan fungsi-fungsi ini untuk melakukan pemrosesan tambahan yang ditentukan pemanggil, seperti melacak penggunaan memori dinamisnya sendiri dengan mempertahankan status tentang jumlah entri yang dialokasikan dan gratis.

Jika pemanggil ExInitializePagedLookasideList memasok fungsi Alokasi Xxx, fungsi tersebut harus mengalokasikan entri untuk daftar lookaside menggunakan parameter input yang diberikan saat memanggil ExAllocatePoolWithTag.

Dimulai dengan Windows Vista, rutinitas serupa, ExInitializeLookasideListEx, menginisialisasi daftar lookaside yang dijelaskan oleh struktur LOOKASIDE_LIST_EX . Tidak seperti rutinitas XxxAllocate dan XxxFree untuk daftar lookaside yang menggunakan struktur PAGED_LOOKASIDE_LIST , rutinitas alokasi dan dealokasi untuk daftar lookaside yang menggunakan struktur LOOKASIDE_LIST_EX menerima penunjuk konteks sebagai parameter input. Rutinitas ini dapat menggunakan konteks ini untuk menyimpan data privat untuk daftar pencarian. Jika driver Anda hanya dimaksudkan untuk berjalan di Windows Vista dan versi Windows yang lebih baru, pertimbangkan untuk menggunakan ExInitializeLookasideListEx alih-alih ExInitializePagedLookasideList. Untuk informasi selengkapnya, lihat Menggunakan Lists Lookaside.

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm)