Freigeben über

MmGetSystemAddressForMdlSafe-Funktion (wdm.h)

  • Artikel

Das Makro MmGetSystemAddressForMdlSafe gibt eine virtuelle Adresse für den Puffer zurück, den der angegebene MDL beschreibt.

Syntax

PVOID MmGetSystemAddressForMdlSafe(
  [in] PMDL  Mdl,
  [in] ULONG Priority
);

Parameter

[in] Mdl

Zeiger auf einen Puffer, dessen entsprechende virtuelle Basisadresse zugeordnet werden soll.

[in] Priority

Gibt einen MM_PAGE_PRIORITY Wert an, der angibt, wie wichtig der Erfolg unter niedrig verfügbaren PTE-Bedingungen ist. Geben Sie den Prioritätswert LowPagePriority, NormalPagePriority oder HighPagePriority an. Ab Windows 8 kann der angegebene Prioritätswert bitweise-ORed mit den Flags MdlMappingNoWrite oder MdlMappingNoExecute sein.

  • LowPagePriority gibt an, dass die Zuordnungsanforderung fehlschlagen kann, wenn das System relativ wenig Ressourcen hat. Ein Beispiel für diese Situation ist eine nicht kritische Netzwerkverbindung, bei der der Treiber den Zuordnungsfehler behandeln kann.

  • NormalPagePriority gibt an, dass die Zuordnungsanforderung fehlschlagen kann, wenn das System sehr ressourcenarm ist. Ein Beispiel für diese Situation ist eine nicht kritische lokale Dateisystemanforderung.

  • HighPagePriority gibt an, dass die Zuordnungsanforderung nicht fehlschlagen darf, es sei denn, das System verfügt über keine vollständigen Ressourcen. Ein Beispiel für diese Situation ist der Auslagerungsdateipfad in einem Treiber.

  • MdlMappingNoWrite gibt an, dass die zugeordneten physischen Seiten als Schreibzugriff (schreibgeschützter) Arbeitsspeicher konfiguriert werden sollen. Ab Windows 8 kann dieses Flagbit bitweise-ORed mit dem MM_PAGE_PRIORITY Wert sein, um Arbeitsspeicher anzugeben, in dem Schreibvorgänge deaktiviert sind.

  • MdlMappingNoExecute gibt an, dass die zugeordneten physischen Seiten als Arbeitsspeicher ohne Ausführung konfiguriert werden sollen. Ab Windows 8 kann dieses Flagbit bitweise-ORed mit dem MM_PAGE_PRIORITY Wert verwendet werden, um arbeitsspeicher anzugeben, in dem die Anweisungsausführung deaktiviert ist. Als bewährte Methode sollten Treiber, die für Windows 8 und höhere Versionen von Windows geschrieben wurden, immer Arbeitsspeicher ohne Ausführung angeben, es sei denn, ausführbarer Arbeitsspeicher ist explizit erforderlich.

Rückgabewert

MmGetSystemAddressForMdlSafe gibt die virtuelle Basisadresse des Systemraums zurück, die den physischen Seiten zugeordnet wird, die von der angegebenen MDL beschrieben werden. Wenn die Seiten nicht bereits dem Systemadressraum zugeordnet sind und der Versuch, sie zu zuordnen, fehlschlägt, wird NULL zurückgegeben.

Hinweise

Diese Routine ordnet die physischen Seiten, die von der angegebenen MDL beschrieben werden, dem Systemadressraum zu, sofern sie nicht bereits dem Systemadressraum zugeordnet sind.

Treiber von programmierten I/O-Geräten (PIO) rufen diese Routine auf, um einen Benutzermoduspuffer, der von der MDL unter Irp-MdlAddress> beschrieben wird und der bereits einem virtuellen Adressbereich im Benutzermodus zugeordnet ist, einem Bereich im Systemadressraum zuzuordnen.

Beim Einstieg in diese Routine muss die angegebene MDL physische Seiten beschreiben, die gesperrt sind. Eine gesperrte MDL kann mithilfe der Routinen MmProbeAndLockPages, MmBuildMdlForNonPagedPool, IoBuildPartialMdl oder MmAllocatePagesForMdlEx erstellt werden.

Wenn die system-address-space-Zuordnung, die von MmGetSystemAddressForMdlSafe zurückgegeben wird, nicht mehr benötigt wird, muss sie freigegeben werden. Die schritte, die zum Freigeben der Zuordnung erforderlich sind, hängen davon ab, wie die MDL erstellt wurde. Dies sind die vier möglichen Fälle:

  • Wenn die MDL durch einen Aufruf der MmProbeAndLockPages-Routine erstellt wurde, ist es nicht erforderlich, die Systemadressraumzuordnung explizit freizugeben. Stattdessen gibt ein Aufruf der MmUnlockPages-Routine die Zuordnung frei, wenn eine zugewiesen wurde.

  • Wenn die MDL durch einen Aufruf der MmBuildMdlForNonPagedPool-Routine erstellt wurde, verwendet MmGetSystemAddressForMdlSafe die vorhandene System-Adressraumzuordnung, anstatt eine neue zu erstellen. In diesem Fall ist keine Bereinigung erforderlich (d. h. entsperren und aufheben sind nicht erforderlich).

  • Wenn die MDL durch einen Aufruf der IoBuildPartialMdl-Routine erstellt wurde, muss der Treiber entweder die MmPrepareMdlForReuse-Routine oder die IoFreeMdl-Routine aufrufen, um die Systemadressraumzuordnung freizugeben.

  • Wenn die MDL durch einen Aufruf der MmAllocatePagesForMdlEx-Routine erstellt wurde, muss der Treiber die MmUnmapLockedPages-Routine aufrufen, um die Systemadressenraumzuordnung freizugeben. Wenn MmGetSystemAddressForMdlSafe für eine MDL mehrmals aufgerufen wird, geben nachfolgende MmGetSystemAddressForMdlSafe-Aufrufe einfach die Zuordnung zurück, die durch den ersten Aufruf erstellt wurde. Ein Aufruf von MmUnmapLockedPages reicht aus, um diese Zuordnung freizugeben.

Ab Windows 7 und Windows Server 2008 R2 ist es nicht erforderlich, MmUnmapLockedPages explizit für eine MDL aufzurufen, die von MmAllocatePagesForMdlEx erstellt wurde. Stattdessen gibt ein Aufruf der MmFreePagesFromMdl-Routine die Systemadressraumzuordnung frei, wenn eine zugewiesen wurde.

Um eine neue Systemadress-Space-Zuordnung zu erstellen, ruft MmGetSystemAddressForMdlSafeMmMapLockedPagesSpecifyCache auf, wobei der CacheType-Parameter auf MmCached festgelegt ist. Ein Treiber, der einen anderen Cachetyp als MmCached erfordert, sollte MmMapLockedPagesSpecifyCache direkt aufrufen, anstatt MmGetSystemAddressForMdlSafe aufzurufen. Weitere Informationen zum CacheType-Parameter finden Sie unter MmMapLockedPagesSpecifyCache.

In einem Aufruf von MmMapLockedPagesSpecifyCache wird der angegebene Cachetyp nur verwendet, wenn den seiten, die von der MDL beschrieben werden, nicht bereits ein 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, wodurch der Cachetyp unabhängig vom ursprünglichen Cachetyp der Seiten auf MmCached festgelegt wird.

Nur ein Thread gleichzeitig kann MmGetSystemAddressForMdlSafe für eine bestimmte MDL sicher aufrufen, da diese Routine davon ausgeht, dass der aufrufende Thread die MDL besitzt. MmGetSystemAddressForMdlSafe kann jedoch mehrmals für dieselbe MDL aufgerufen werden, indem entweder alle Aufrufe aus demselben Thread ausgeführt werden oder, wenn die Aufrufe von mehreren Threads stammen, durch explizite Synchronisierung der Aufrufe.

Wenn ein Treiber eine Anforderung in kleinere Anforderungen aufteilen muss, kann der Treiber zusätzliche MDLs zuweisen, oder der Treiber kann die IoBuildPartialMdl-Routine verwenden.

Die zurückgegebene Basisadresse hat den gleichen Offset wie die virtuelle Adresse in der MDL.

Windows 98 unterstützt MmGetSystemAddressForMdlSafe nicht. Verwenden Sie stattdessen MmGetSystemAddressForMdl .

Da dieses Makro MmMapLockedPagesSpecifyCache aufruft, erfordert die Verwendung möglicherweise eine Verknüpfung mit NtosKrnl.lib.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000
Kopfzeile wdm.h
IRQL <= DISPATCH_LEVEL
DDI-Complianceregeln MdlAfterReqCompletedIntIoctlA(kmdf), MdlAfterReqCompletedIoctlA(kmdf), MdlAfterReqCompletedReadA(kmdf), MdlAfterReqCompletedWriteA(kmdf)