Fungsi MmMapLockedPagesSpecifyCache (wdm.h)

Artikel
03/08/2023

Rutinitas MmMapLockedPagesSpecifyCache memetakan halaman fisik yang dijelaskan oleh MDL ke alamat virtual, dan memungkinkan pemanggil menentukan atribut cache yang digunakan untuk membuat pemetaan.

Sintaks

PVOID MmMapLockedPagesSpecifyCache(
  [in]           PMDL                                                                          MemoryDescriptorList,
  [in]           __drv_strictType(KPROCESSOR_MODE / enum _MODE,__drv_typeConst)KPROCESSOR_MODE AccessMode,
  [in]           __drv_strictTypeMatch(__drv_typeCond)MEMORY_CACHING_TYPE                      CacheType,
  [in, optional] PVOID                                                                         RequestedAddress,
  [in]           ULONG                                                                         BugCheckOnFailure,
  [in]           ULONG                                                                         Priority
);

Parameter

[in] MemoryDescriptorList

Penunjuk ke MDL yang akan dipetakan. MDL ini harus menjelaskan halaman fisik yang dikunci. MDL yang terkunci dapat dibangun oleh rutinitas MmProbeAndLockPages atau MmAllocatePagesForMdlEx . Untuk pemetaan ke ruang pengguna, MDL yang dibangun oleh rutinitas MmBuildMdlForNonPagedPool dapat digunakan.

[in] AccessMode

Menentukan mode akses untuk memetakan MDL: KernelMode atau UserMode. Hampir semua driver harus menggunakan KernelMode.

[in] CacheType

Menentukan nilai MEMORY_CACHING_TYPE , yang menunjukkan atribut cache yang akan digunakan untuk memetakan MDL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in, optional] RequestedAddress

Jika AccessMode = UserMode, parameter ini menentukan alamat virtual pengguna awal untuk memetakan MDL ke, atau diatur ke NULL untuk memungkinkan sistem memilih alamat awal. Sistem mungkin membulatkan alamat yang diminta agar sesuai dengan persyaratan batas alamat, sehingga pemanggil harus memeriksa nilai yang dikembalikan.

[in] BugCheckOnFailure

Menentukan perilaku rutinitas untuk AccessMode = KernelMode jika MDL tidak dapat dipetakan karena sumber daya sistem yang rendah. Jika TRUE, sistem mengeluarkan pemeriksaan bug. Jika FALSE, rutinitas mengembalikan NULL. Driver harus mengatur parameter ini ke FALSE.

[in] Priority

Nilai MM_PAGE_PRIORITY yang menunjukkan pentingnya keberhasilan ketika entri tabel halaman (PTEs) langka. Dimulai dengan Windows 8, nilai prioritas yang ditentukan dapat menjadi bitwise-ORed dengan bendera MdlMappingNoWrite atau MdlMappingNoExecute untuk menentukan memori di mana eksekusi tulis atau instruksi dinonaktifkan. Untuk informasi selengkapnya tentang nilai yang mungkin untuk Prioritas, lihat MmGetSystemAddressForMdlSafe.

Nilai kembali

MmMapLockedPagesSpecifyCache mengembalikan alamat awal halaman yang dipetakan. Jika halaman tidak dapat dipetakan dan BugCheckOnFailureFALSE, rutin mengembalikan NULL.

Keterangan

Gunakan MmUnmapLockedPages untuk membatalkan pemetaan halaman fisik yang dipetakan oleh MmMapLockedPagesSpecifyCache.

Jika AccessMode adalah KernelMode, dan jika MmMapLockedPagesSpecifyCache tidak dapat memetakan halaman yang ditentukan, rutin mengembalikan NULL (jika BugCheckOnFailure = FALSE), atau sistem operasi mengeluarkan pemeriksaan bug (jika BugCheckOnFailure = TRUE).

Jika AccessMode adalah UserMode, ketahui detail berikut:

Jika halaman yang ditentukan tidak dapat dipetakan, rutinitas akan menimbulkan pengecualian. Pemanggil yang menentukan UserMode harus membungkus panggilan ke MmMapLockedPagesSpecifyCache dalam blok coba/kecuali . Untuk informasi selengkapnya, lihat Menangani Pengecualian.
Rutinitas mengembalikan alamat pengguna yang valid dalam konteks proses di mana driver berjalan. Misalnya, jika driver 64-bit berjalan dalam konteks aplikasi 32-bit, buffer dipetakan ke alamat dalam rentang alamat 32-bit aplikasi.
Pemetaan yang tidak dapat dieksekusi selalu dibuat saat AccessMode adalah UserMode. Oleh karena itu, menggunakan bendera MdlMappingNoExecute dengan parameter Prioritas tidak perlu dalam skenario ini. Namun, bendera MdlMappingNoWrite masih dapat digunakan dengan parameter Prioritas dalam skenario ini untuk meminta pemetaan baca-saja.
Perlindungan pemetaan yang tidak dapat dieksekusi dan perlindungan tulis pemetaan apa pun yang ditentukan dengan menggunakan bendera MdlMappingNoWrite dengan parameter Prioritas tidak dapat diubah oleh kode yang berjalan dalam mode pengguna. Misalnya, jika driver memetakan beberapa halaman ke dalam proses pengguna dan menentukan bendera MdlMappingNoWrite , sistem menjamin bahwa proses tidak dapat mengubah halaman.

Rutinitas menggunakan parameter CacheType hanya jika halaman yang dijelaskan oleh MDL belum memiliki jenis cache yang terkait dengannya. Namun, dalam hampir semua kasus, halaman sudah memiliki jenis cache terkait, dan jenis cache ini digunakan oleh pemetaan baru. Pengecualian untuk aturan ini adalah untuk halaman yang dialokasikan oleh MmAllocatePagesForMdl, yang tidak memiliki jenis cache tertentu yang terkait dengannya. Untuk halaman tersebut, parameter CacheType menentukan jenis cache pemetaan.

Driver tidak boleh mencoba membuat lebih dari satu pemetaan ruang alamat sistem untuk MDL. Selain itu, karena MDL yang dibangun oleh rutinitas MmBuildMdlForNonPagedPool sudah dipetakan ke ruang alamat sistem, driver tidak boleh mencoba memetakan MDL ini ke ruang alamat sistem lagi dengan menggunakan rutinitas MmMapLockedPagesSpecifyCache (meskipun membuat pemetaan ruang alamat pengguna diizinkan). Jika tidak diketahui apakah MDL yang terkunci sudah memiliki pemetaan ruang alamat sistem, driver dapat menggunakan makro MmGetSystemAddressForMdlSafe alih-alih MmMapLockedPagesSpecifyCache. Jika MDL sudah dipetakan ke ruang alamat sistem, MmGetSystemAddressForMdlSafe akan mengembalikan pemetaan ruang alamat sistem yang ada alih-alih membuat pemetaan baru.

Peringatan

Driver yang memetakan memori kernel ke ruang alamat pengguna harus menghindari mengekspos data kernel yang berpotensi sensitif ke proses yang tidak tepercaya. Buffer yang tidak diinisialisasi, seperti buffer yang dialokasikan dari kumpulan, harus secara eksplisit diisi dengan nol sebelum dipetakan. Selain itu, ukuran buffer mode pengguna yang dialokasikan dari kumpulan harus berupa kelipatan ukuran halaman memori virtual untuk mencegah bagian mana pun dari halaman dalam buffer digunakan untuk alokasi lain. Akhirnya, buffer tidak boleh dibebaskan kembali ke kumpulan saat masih dipetakan ke ruang alamat pengguna.

Jika AccessMode adalah UserMode, pemanggil harus berjalan di IRQL <= APC_LEVEL. Jika AccessMode adalah KernelMode, pemanggil harus berjalan di IRQL <= DISPATCH_LEVEL.

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Lihat bagian Keterangan.
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport)