MmMapLockedPagesSpecifyCache-Funktion (wdm.h)

Artikel
03/08/2023

Die MmMapLockedPagesSpecifyCache-Routine ordnet die physischen Seiten, die von einer MDL beschrieben werden, einer virtuellen Adresse zu und ermöglicht es dem Aufrufer, das Cacheattribut anzugeben, das zum Erstellen der Zuordnung verwendet wird.

Syntax

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

Ein Zeiger auf die MDL, die zugeordnet werden soll. Diese MDL muss physische Seiten beschreiben, die gesperrt sind. Eine gesperrte MDL kann mit der Routine MmProbeAndLockPages oder MmAllocatePagesForMdlEx erstellt werden. Für Zuordnungen zum Benutzerbereich können MDLs verwendet werden, die von der MmBuildMdlForNonPagedPool-Routine erstellt werden.

[in] AccessMode

Gibt den Zugriffsmodus an, in dem die MDL zugeordnet werden soll: KernelMode oder UserMode. Fast alle Treiber sollten KernelMode verwenden.

[in] CacheType

Gibt einen MEMORY_CACHING_TYPE Wert an, der das Cache-Attribut angibt, das zum Zuordnen der MDL verwendet werden soll. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] RequestedAddress

Bei AccessMode = UserMode gibt dieser Parameter die virtuelle Startadresse des Benutzers an, der die MDL zugeordnet werden soll, oder auf NULL festgelegt, damit das System die Startadresse auswählen kann. Das System kann die angeforderte Adresse entsprechend den Anforderungen an die Adressgrenze abrunden, sodass Aufrufer den Rückgabewert überprüfen müssen.

[in] BugCheckOnFailure

Gibt das Verhalten der Routine für AccessMode = KernelMode an, wenn die MDL aufgrund geringer Systemressourcen nicht zugeordnet werden kann. True gibt an, dass das System eine Fehlerprüfung ausgibt. Wenn FALSE, gibt die Routine NULL zurück. Treiber müssen diesen Parameter auf FALSE festlegen.

[in] Priority

Ein MM_PAGE_PRIORITY Wert, der angibt, wie wichtig der Erfolg ist, wenn Seitentabelleneinträge (PTEs) knapp sind. Ab Windows 8 kann der angegebene Prioritätswert bitweise-ORed mit den Flags MdlMappingNoWrite oder MdlMappingNoExecute verwendet werden, um Arbeitsspeicher anzugeben, in dem Schreibvorgänge oder Die Anweisungsausführung deaktiviert sind. Weitere Informationen zu den möglichen Werten für Priority finden Sie unter MmGetSystemAddressForMdlSafe.

Rückgabewert

MmMapLockedPagesSpecifyCache gibt die Startadresse der zugeordneten Seiten zurück. Wenn die Seiten nicht zugeordnet werden können und BugCheckOnFailureauf FALSE festgelegt ist, gibt die Routine NULL zurück.

Hinweise

Verwenden Sie MmUnmapLockedPages , um die Zuordnung der physischen Seiten aufzuheben, die von MmMapLockedPagesSpecifyCache zugeordnet wurden.

Wenn AccessModeKernelMode ist und MmMapLockedPagesSpecifyCache die angegebenen Seiten nicht zuordnen kann, gibt die Routine NULL zurück (wenn BugCheckOnFailure = FALSE) oder das Betriebssystem eine Fehlerüberprüfung ausgibt (wenn BugCheckOnFailure = TRUE).

Wenn AccessModeDen UserMode aufweist, beachten Sie die folgenden Details:

Wenn die angegebenen Seiten nicht zugeordnet werden können, löst die Routine eine Ausnahme aus. Aufrufer, die UserMode angeben, müssen den Aufruf von MmMapLockedPagesSpecifyCache in einem try/except-Block umschließen. Weitere Informationen finden Sie unter Behandeln von Ausnahmen.
Die Routine gibt eine Benutzeradresse zurück, die im Kontext des Prozesses gültig ist, in dem der Treiber ausgeführt wird. Wenn beispielsweise ein 64-Bit-Treiber im Kontext einer 32-Bit-Anwendung ausgeführt wird, wird der Puffer einer Adresse im 32-Bit-Adressbereich der Anwendung zugeordnet.
Eine nicht ausführbare Zuordnung wird immer erstellt, wenn AccessModeauf UserMode festgelegt ist. Daher ist die Verwendung des MdlMappingNoExecute-Flags mit dem Priority-Parameter in diesem Szenario nicht erforderlich. Das Flag "MdlMappingNoWrite " kann in diesem Szenario jedoch weiterhin mit dem Parameter Priority verwendet werden, um eine schreibgeschützte Zuordnung anzufordern.
Der nicht ausführbare Schutz der Zuordnung und jeglicher Schreibschutz der Zuordnung, die mithilfe des MdlMappingNoWrite-Flags mit dem Priority-Parameter angegeben wird, kann nicht durch Code geändert werden, der im Benutzermodus ausgeführt wird. Wenn beispielsweise ein Treiber einige Seiten einem Benutzerprozess zuordnet und das MdlMappingNoWrite-Flag angibt, garantiert das System, dass der Prozess die Seiten nicht ändern kann.

Die Routine verwendet den CacheType-Parameter nur, wenn den seiten, die von der MDL beschrieben werden, noch kein Cachetyp zugeordnet ist. In fast allen Fällen verfügen die Seiten jedoch bereits über einen zugeordneten Cachetyp, und dieser Cachetyp wird von der neuen Zuordnung verwendet. Eine Ausnahme von dieser Regel gilt für Seiten, die von MmAllocatePagesForMdl zugeordnet werden und denen kein bestimmter Cachetyp zugeordnet ist. Für solche Seiten bestimmt der CacheType-Parameter den Cachetyp der Zuordnung.

Ein Treiber darf nicht versuchen, mehr als eine Systemadressraumzuordnung für eine MDL zu erstellen. Da eine MDL, die von der MmBuildMdlForNonPagedPool-Routine erstellt wird, bereits dem Systemadressraum zugeordnet ist, darf ein Treiber nicht versuchen, diese MDL mithilfe der MmMapLockedPagesSpecifyCache-Routine erneut dem Systemadressraum zuzuordnen (obwohl das Erstellen von Benutzer-Adressraumzuordnungen zulässig ist). Wenn nicht bekannt ist, ob eine gesperrte MDL bereits über eine Systemadressraumzuordnung verfügt, kann ein Treiber das Makro MmGetSystemAddressForMdlSafe anstelle von MmMapLockedPagesSpecifyCache verwenden. Wenn die MDL bereits dem Systemadressraum zugeordnet ist, gibt MmGetSystemAddressForMdlSafe die vorhandene Systemadressraumzuordnung zurück, anstatt eine neue Zuordnung zu erstellen.

Warnung

Ein Treiber, der den Kernelspeicher dem Benutzeradressraum zuordnet, muss verhindern, dass potenziell sensible Kerneldaten für nicht vertrauenswürdige Prozesse verfügbar sind. Nicht initialisierte Puffer, z. B. Puffer, die aus dem Pool zugeordnet werden, müssen explizit mit Nullen gefüllt werden, bevor sie zugeordnet werden. Darüber hinaus muss die Größe eines Benutzermoduspuffers, der aus dem Pool zugeordnet wird, ein Vielfaches der Seitengröße des virtuellen Arbeitsspeichers sein, um zu verhindern, dass ein Teil der Seiten im Puffer für andere Zuordnungen verwendet wird. Schließlich dürfen Puffer nicht wieder in den Pool freigegeben werden, während sie noch dem Benutzeradressraum zugeordnet sind.

Wenn AccessModeDen UserMode aufweist, muss der Aufrufer unter IRQL <= APC_LEVEL ausgeführt werden. Wenn AccessModeKernelMode ist, muss der Aufrufer unter IRQL <= DISPATCH_LEVEL ausgeführt werden.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport)