MmMapLockedPagesSpecifyCache-Funktion (wdm.h)
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 von der MmProbeAndLockPages oder MmAllocatePagesForMdlEx Routine erstellt werden. Für Zuordnungen zum Benutzerbereich können MDLs, die von der MmBuildMdlForNonPagedPool Routine erstellt werden, verwendet 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
Wenn AccessMode = UserMode-, gibt dieser Parameter die virtuelle Startadresse des Benutzers an, der die MDL zugeordnet werden soll, oder legt diese auf NULL- fest, damit das System die Startadresse auswählen kann. Das System kann die angeforderte Adresse auf die Anforderungen an die Grenze abrunden, sodass Anrufer den Rückgabewert überprüfen müssen.
[in] BugCheckOnFailure
Gibt das Verhalten der Routine für AccessMode = KernelMode- an, wenn die MDL aufgrund niedriger Systemressourcen nicht zugeordnet werden kann. Wenn TRUE, gibt das System eine Fehlerüberprüfung aus. 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 mit dem MdlMappingNoWrite oder MdlMappingNoExecute Flags angegeben werden, um Arbeitsspeicher anzugeben, in dem Schreib- oder Anweisungsausführung deaktiviert ist. Weitere Informationen zu den möglichen Werten für Priorityfinden Sie unter MmGetSystemAddressForMdlSafe.
Rückgabewert
MmMapLockedPagesSpecifyCache gibt die Startadresse der zugeordneten Seiten zurück. Wenn die Seiten nicht zugeordnet werden können und BugCheckOnFailureFALSEist, gibt die Routine NULL-zurück.
Bemerkungen
Verwenden Sie MmUnmapLockedPages-, um die Zuordnung der physischen Seiten aufzuheben, die von MmMapLockedPagesSpecifyCache-zugeordnet wurden.
Wenn AccessMode-KernelModeist und wenn MmMapLockedPagesSpecifyCache die angegebenen Seiten nicht zuordnen kann, die Routine gibt NULL- zurück (wenn BugCheckOnFailure = FALSE), oder das Betriebssystem gibt eine Fehlerüberprüfung aus (wenn BugCheckOnFailure = TRUE).
Wenn AccessMode-UserMode-ist, 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 an 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 AccessMode-UserMode-ist. Daher ist die Verwendung des MdlMappingNoExecute- Flags mit dem parameter Priority in diesem Szenario nicht erforderlich. Das MdlMappingNoWrite Flag kann jedoch weiterhin mit dem parameter Priority in diesem Szenario verwendet werden, um eine schreibgeschützte Zuordnung anzufordern.
Der nicht ausführbare Schutz der Zuordnung und der Schreibschutz der Zuordnung, die mithilfe des MdlMappingNoWrite- Flags mit dem Parameter Priority parameter angegeben wird, können nicht durch Code geändert werden, der im Benutzermodus ausgeführt wird. Wenn ein Treiber beispielsweise einige Seiten einem Benutzerprozess zuordnet und die MdlMappingNoWrite-Flag angibt, garantiert das System, dass der Prozess die Seiten nicht ändern kann.
Die Routine verwendet den CacheType Parameter nur, wenn die von der MDL beschriebenen Seiten noch keinen Cachetyp zugeordnet haben. 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 dieser Regel ist für Seiten, die von MmAllocatePagesForMdlzugeordnet werden, die keinem bestimmten Cachetyp zugeordnet sind. 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, muss ein Treiber nicht versuchen, diese MDL erneut in den Systemadressraum zuzuordnen, indem die MmMapLockedPagesSpecifyCache Routine verwendet wird (obwohl das Erstellen von Benutzeradressraumzuordnungen zulässig ist). Wenn nicht bekannt ist, ob eine gesperrte MDL bereits über eine Systemadressraumzuordnung verfügt, kann ein Treiber das MmGetSystemAddressForMdlSafe Makro 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 in den Benutzeradressraum zuordnet, muss verhindern, dass potenziell vertrauliche Kerneldaten für nicht vertrauenswürdige Prozesse verfügbar sind. Nicht initialisierte Puffer, z. B. Puffer, die aus dem Pool zugeordnet sind, müssen explizit mit Nullen gefüllt werden, bevor sie zugeordnet werden. Darüber hinaus muss die Größe eines vom Pool zugewiesenen Benutzermoduspuffers ein Vielfaches der Größe der virtuellen Speicherseite 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 AccessMode-UserMode-ist, muss der Aufrufer unter IRQL <= APC_LEVEL ausgeführt werden. Wenn AccessMode-KernelMode-ist, muss der Aufrufer unter IRQL <= DISPATCH_LEVEL ausgeführt werden.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Universal |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | Siehe Abschnitt "Hinweise". |
| DDI-Complianceregeln | HwStorPortProhibitedDIs(storport) |