ALLOCATE_FUNCTION_EX fungsi panggilan balik (wdm.h)

Artikel
03/08/2023

LookasideListAllocateEx rutin mengalokasikan penyimpanan untuk entri daftar lookaside baru saat klien meminta entri dari daftar lookaside yang kosong.

Sintaks

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

PVOID AllocateFunctionEx(
  [in]      POOL_TYPE PoolType,
  [in]      SIZE_T NumberOfBytes,
  [in]      ULONG Tag,
  [in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}

Parameter

[in] PoolType

Menentukan jenis penyimpanan yang akan dialokasikan untuk entri daftar lookaside baru. Pemanggil mengatur parameter ini ke nilai enumerasi POOL_TYPE yang valid, dan mungkin menggigit OU nilai ini dengan salah satu bit bendera berikut:

POOL_RAISE_IF_ALLOCATION_FAILURE
POOL_QUOTA_FAIL_INSTEAD_OF_RAISE

Untuk informasi selengkapnya tentang bendera POOL_RAISE_IF_ALLOCATION_FAILURE, lihat ExAllocatePoolWithTag. Untuk informasi selengkapnya tentang bendera POOL_QUOTA_FAIL_INSTEAD_OF_RAISE, lihat ExAllocatePoolWithQuotaTag.

Jika, dalam panggilan ExInitializeLookasideListEx yang menginisialisasi daftar lookaside, parameter Flags adalah nol, parameter PoolType yang diterima rutin LookasideListAllocateEx adalah nilai parameter PoolType yang sama yang diteruskan ke ExInitializeLookasideListEx.

Jika, dalam panggilan ExInitializeLookasideListEx , Bendera = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL, parameter PoolType yang diterima rutin LookasideListAllocateEx adalah bitwise ATAU dari POOL_RAISE_IF_ALLOCATION_FAILURE dan nilai parameter PoolType yang diteruskan ke ExInitializeLookasideListEx. Rutinitas LookasideListAllocateEx dapat meneruskan nilai parameter PoolType-nya , tanpa modifikasi, ke rutinitas ExAllocatePoolWithTag .

Jika, dalam panggilan ExInitializeLookasideListEx , Bendera = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE, parameter PoolType yang diterima rutin LookasideListAllocateEx adalah bitwise ATAU dari POOL_QUOTA_FAIL_INSTEAD_OF_RAISE dan nilai PoolType yang diteruskan ke ExInitializeLookasideListEx. Rutinitas LookasideListAllocateEx dapat meneruskan nilai parameter PoolType-nya , tanpa modifikasi, ke rutinitas ExAllocatePoolWithQuotaTag .

[in] NumberOfBytes

Menentukan ukuran, dalam byte, dari entri daftar lookaside untuk dialokasikan.

[in] Tag

Menentukan tag kumpulan empat byte yang akan digunakan untuk menandai penyimpanan yang dialokasikan untuk entri daftar lookaside baru. Untuk informasi selengkapnya tentang tag kumpulan, lihat deskripsi parameter Tag di ExAllocatePoolWithTag.

[in, out] Lookaside

Penunjuk ke struktur LOOKASIDE_LIST_EX yang menjelaskan daftar lookaside. Struktur ini sebelumnya diinisialisasi oleh rutinitas ExInitializeLookasideListEx .

Nilai kembali

LookasideListAllocateEx mengembalikan penunjuk ke entri lookaside-list yang dialokasikan. Jika rutinitas tidak dapat mengalokasikan entri, maka akan mengembalikan NULL.

Keterangan

Driver yang membuat daftar lookaside dapat mengimplementasikan rutinitas LookasideListAllocateEx untuk mengalokasikan buffer secara dinamis untuk daftar. Buffer yang tidak digunakan disimpan sebagai entri dalam daftar. Semua entri dalam daftar tampilan adalah buffer dengan ukuran seragam, yang ditentukan driver ketika daftar diinisialisasi.

Driver menyediakan pointer ke rutinitas LookasideListAllocateEx kustom sebagai parameter input dalam panggilan ExInitializeLookasideListEx yang menginisialisasi daftar lookaside. Jika driver mengatur parameter ini ke NULL, daftar lookaside menggunakan rutinitas alokasi default sebagai gantinya.

Driver memanggil rutinitas ExAllocateFromLookasideListEx untuk mengalokasikan entri dari daftar lookaside. Jika daftar kosong (tidak berisi entri), ExAllocateFromLookasideListEx memanggil LookasideListAllocateEx untuk mengalokasikan penyimpanan secara dinamis untuk entri baru. LookasideListAllocateEx mengembalikan penunjuk ke entri yang baru dialokasikan jika alokasi berhasil. Jika tidak, ia mengembalikan NULL.

Parameter PoolType, NumberOfBytes, Tag, dan Lookaside berisi nilai yang sama yang diteruskan sebagai parameter input dalam panggilan ExInitializeLookasideListEx yang menginisialisasi daftar lookaside.

Rutinitas LookasideListAllocateEx dapat menggunakan parameter Lookaside untuk mengakses data konteks privat yang telah dikaitkan dengan daftar lookaside driver. Untuk informasi selengkapnya, lihat contoh kode di ExInitializeLookasideListEx.

Untuk informasi selengkapnya tentang daftar lookaside, lihat Menggunakan lookaside Lists.

Rutinitas LookasideListAllocateEx dipanggil pada IRQL yang sama dengan panggilan ke ExAllocateFromLookasideListEx yang meminta entri. Untuk panggilan yang meminta entri yang berada dalam memori halaman, pemanggil harus menjalankan IRQL <= APC_LEVEL. Untuk panggilan yang meminta entri yang berada dalam memori yang tidak disebarkan, pemanggil harus menjalankan IRQL <= DISPATCH_LEVEL.

Contoh

Untuk menentukan rutinitas panggilan balik LookasideListAllocateEx , Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis rutinitas panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk driver. Mendeklarasikan fungsi menggunakan jenis fungsi panggilan balik membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya menemukan kesalahan, dan itu adalah persyaratan untuk menulis driver untuk sistem operasi Windows.

Misalnya, untuk menentukan rutinitas panggilan balik LookasideListAllocateEx yang diberi nama MyLookasideListAllocateEx, gunakan jenis FREE_FUNCTION_EX seperti yang ditunjukkan dalam contoh kode ini:

FREE_FUNCTION_EX MyLookasideListFreeEx;

Kemudian, terapkan rutinitas panggilan balik Anda sebagai berikut:

_Use_decl_annotations_
VOID
  MyLookasideListFreeEx(
    PVOID  Buffer,
    PLOOKASIDE_LIST_EX  Lookaside
    )
  {
      // Function body
  }

Jenis fungsi FREE_FUNCTION_EX didefinisikan dalam file header Wdm.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan _Use_decl_annotations_ anotasi ke definisi fungsi Anda. Anotasi _Use_decl_annotations_ memastikan bahwa anotasi yang diterapkan ke jenis fungsi FREE_FUNCTION_EX dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver WDM. Untuk informasi tentang _Use_decl_annotations_, lihat Menganotasi Perilaku Fungsi.