Freigeben über

MmGetSystemAddressForMdlSafe-Funktion (wdm.h)

  • Artikel

Das MmGetSystemAddressForMdlSafe Makro gibt eine nicht ausgelagerte virtuelle Adresse für den Puffer zurück, den die 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 die Wichtigkeit des Erfolgs unter niedrigen verfügbaren PTE-Bedingungen angibt. Geben Sie einen Prioritätswert LowPagePriority-, NormalPagePriority-oder HighPagePriority-an. Ab Windows 8 kann der angegebene Prioritätswert bitweise mit dem MdlMappingNoWrite oder MdlMappingNoExecute Flags bitweise oRediert werden.

  • LowPagePriority gibt an, dass die Zuordnungsanforderung fehlschlagen kann, wenn das System relativ niedrig für Ressourcen ist. 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 bei Ressourcen sehr niedrig 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 ist vollständig aus Ressourcen entfernt. Ein Beispiel für diese Situation ist der Auslagerungsdateipfad in einem Treiber.

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

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

Rückgabewert

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

Bemerkungen

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

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

Bei der Eingabe in diese Routine muss die angegebene MDL physische Seiten beschreiben, die gesperrt sind. Eine gesperrte MDL kann mithilfe der MmProbeAndLockPages, MmBuildMdlForNonPagedPool, IoBuildPartialMdloder MmAllocatePagesForMdlEx Routine erstellt werden.

Wenn die systemadress-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 zugeordnet wurde.

  • Wenn die MDL durch einen Aufruf der MmBuildMdlForNonPagedPool Routine erstellt wurde, verwendet MmGetSystemAddressForMdlSafe die vorhandene Systemadressraumzuordnung wieder, anstatt eine neue zu erstellen. In diesem Fall ist keine Bereinigung erforderlich (d. a. Entsperren und Entsperren sind nicht erforderlich).

  • Wenn die MDL von einem 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 Systemadressraumzuordnung freizugeben. Wenn MmGetSystemAddressForMdlSafe mehrere Mal für eine MDL aufgerufen wird, geben nachfolgende MmGetSystemAddressForMdlSafe Aufrufe einfach die Zuordnung zurück, die vom ersten Aufruf erstellt wurde. Ein Aufruf von MmUnmapLockedPages reicht aus, um diese Zuordnung freizugeben.

Ab Windows 7 und Windows Server 2008 R2 muss nicht explizit MmUnmapLockedPages- für eine MDL aufgerufen werden, die von MmAllocatePagesForMdlExerstellt wurde. Stattdessen gibt ein Aufruf der MmFreePagesFromMdl Routine die Systemadressraumzuordnung frei, wenn eine zugeordnet wurde.

Zum Erstellen einer neuen Systemadressraumzuordnung ruft MmGetSystemAddressForMdlSafeMmMapLockedPagesSpecifyCache auf, wobei der parameter CacheType auf MmCachedfestgelegt ist. Ein Treiber, der einen anderen Cachetyp als MmCached erfordert sollte MmMapLockedPagesSpecifyCache direkt aufrufen, anstatt MmGetSystemAddressForMdlSafeaufzurufen. Weitere Informationen zum parameter CacheType finden Sie unter MmMapLockedPagesSpecifyCache.

In einem Aufruf von MmMapLockedPagesSpecifyCachewird der angegebene Cachetyp nur verwendet, 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, wodurch der Cachetyp unabhängig vom ursprünglichen Cachetyp der Seiten auf MmCached festgelegt wird.

Nur jeweils ein Thread kann MmGetSystemAddressForMdlSafe- für eine bestimmte MDL sicher aufrufen, da bei dieser Routine davon ausgegangen wird, dass der aufrufende Thread die MDL besitzt. MmGetSystemAddressForMdlSafe- kann jedoch mehrere Mal für dieselbe MDL aufgerufen werden, entweder durch Ausführen aller Aufrufe aus demselben Thread oder, wenn die Aufrufe aus mehreren Threads stammen, durch explizite Synchronisierung der Aufrufe.

Wenn ein Treiber eine Anforderung in kleinere Anforderungen aufteilen muss, kann der Treiber zusätzliche MDLs zuordnen, 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 MmGetSystemAddressForMdlSafenicht. Verwenden Sie stattdessen MmGetSystemAddressForMdl-.

Da dieses Makro MmMapLockedPagesSpecifyCache-aufruft, ist möglicherweise eine Verknüpfung mit NtosKrnl.lib erforderlich.

Anforderungen

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