MmAllocatePagesForMdlEx-Funktion (wdm.h)
Die MmAllocatePagesForMdlEx-Routine ordnet einer MDL nicht ausseitige, physische Speicherseiten zu.
Verwenden Sie diese Routine anstelle von MmAllocatePagesForMdl.
Syntax
PMDL MmAllocatePagesForMdlEx(
[in] PHYSICAL_ADDRESS LowAddress,
[in] PHYSICAL_ADDRESS HighAddress,
[in] PHYSICAL_ADDRESS SkipBytes,
[in] SIZE_T TotalBytes,
[in] MEMORY_CACHING_TYPE CacheType,
[in] ULONG Flags
);
Parameter
[in] LowAddress
Gibt die physische Adresse des Anfangs des ersten Adressbereichs an, aus dem die zugeordneten Seiten stammen können. Wenn MmAllocatePagesForMdlEx die angeforderte Anzahl von Bytes im ersten Adressbereich nicht zuordnen kann, durchlaufen sie zusätzliche Adressbereiche, um weitere Seiten abzurufen. Bei jeder Iteration fügt MmAllocatePagesForMdlEx den Wert von SkipBytes zur vorherigen Startadresse hinzu, um den Start des nächsten Adressbereichs abzurufen.
[in] HighAddress
Gibt die physische Adresse des Endes des ersten Adressbereichs an, aus dem die zugeordneten Seiten stammen können.
[in] SkipBytes
Gibt die Anzahl der Bytes an, die vom Anfang des vorherigen Adressbereichs übersprungen werden sollen, aus dem die zugeordneten Seiten stammen können. SkipBytes muss ein ganzzahliges Vielfaches der Seitengröße des virtuellen Arbeitsspeichers in Bytes sein.
[in] TotalBytes
Gibt die Gesamtanzahl der Bytes an, die für die MDL zugewiesen werden sollen.
[in] CacheType
Gibt einen MEMORY_CACHING_TYPE Wert an, der den Typ der Zwischenspeicherung angibt, der für den angeforderten Arbeitsspeicher zulässig ist.
[in] Flags
Gibt Flags für diesen Vorgang an. Legen Sie diesen Parameter auf null oder auf den bitweisen OR eines oder mehrerer der folgenden MM_ALLOCATE_XXX-Flagbits fest:
Die letzten vier Elemente in der vorherigen Liste werden nur in Windows 7 und höheren Versionen von Windows unterstützt.
| Wert | Bedeutung |
|---|---|
| MM_DONT_ZERO_ALLOCATION 0x00000001 | Füllen Sie die zugeordneten Seiten nicht mit Nullen aus. Standardmäßig stellt MmAllocatePagesForMdlEx die seiten, die es zuordnet, auf Null. Wenn Sie diesen Vorgang überspringen, können Sie möglicherweise die Leistung des Aufrufs MmAllocatePagesForMdlEx verbessern. Sie dürfen dieses Flag jedoch nicht verwenden, es sei denn, Sie machen die zugeordneten Seiten nie für Benutzermodusprogramme verfügbar, oder Sie überschreiben immer den ursprünglichen Inhalt der Seiten, bevor Sie die zugeordneten Seiten für Benutzermodusprogramme verfügbar machen. |
| MM_ALLOCATE_FROM_LOCAL_NODE_ONLY 0x00000002 | Weisen Sie Seiten nur vom idealen Knoten zu. Dieses Flag gilt nur für Multiprozessorsysteme, die über nicht einheitliche Speicherzugriffsarchitekturen (NUMA) verfügen. Ab Windows Vista gibt dieses Flag an, dass alle Seiten aus dem idealen Knoten des aktuellen Threads zugeordnet werden müssen. Von anderen Knoten sollen keine Seiten zugeordnet werden. In Versionen von Windows vor Windows Vista gibt dieses Flag an, dass alle Seiten vom lokalen Knoten zugeordnet werden müssen. d. h. vom Knoten, zu dem der aktuelle Prozessor gehört. Weitere Informationen zu NUMA-Multiprozessorsystemen finden Sie unter NUMA-Unterstützung . |
| MM_ALLOCATE_FULLY_REQUIRED 0x00000004 | Eine vollständige Zuordnung ist erforderlich. Ab Windows 7 erfordert dieses Flag, dass MmAllocatePagesForMdlEx NULL zurückgibt, wenn es nicht alle angeforderten Seiten zuordnen kann. Die Routine gibt nur dann einen Nicht-NULL-Wert zurück, wenn die gesamte angeforderte Zuordnung erfolgreich abgerufen wird. Dieses Flag ermöglicht es dem Speicher-Manager, die Zuordnung effizienter durchzuführen, wenn der Aufrufer eine vollständige Zuordnung erfordert. |
| MM_ALLOCATE_NO_WAIT 0x00000008 | Warten Sie nicht. Ab Windows 7 gibt dieses Flag an, dass der MmAllocatePagesForMdlEx-Aufruf den aufrufenden Thread nicht blockieren darf. In der Regel ist der Aufrufer ein Kernelmodustreiber, der bei IRQL < DISPATCH_LEVEL ausgeführt wird, aber nicht zulassen kann, dass seine Ausführung blockiert wird. Beispielsweise kann der Treiber bei Paging- oder Energieverwaltungsvorgängen helfen. Unabhängig davon, ob dieses Flag festgelegt ist, blockiert MmAllocatePagesForMdlEx nie Aufrufer, die unter IRQL = DISPATCH_LEVEL ausgeführt werden. |
| MM_ALLOCATE_PREFER_CONTIGUOUS 0x00000010 | Die Zuordnung erfolgt so, dass die Fragmentierung des Systemspeichers minimiert wird. Ab Windows 7 gibt dieses Flag an, dass der Aufrufer die Fragmentierung des physischen Arbeitsspeichers vermeiden möchte, um anderen Aufrufenden mehr zusammenhängenden Arbeitsspeicher zur Verfügung zu stellen. Die zugeordneten Seiten sind nicht garantiert (und sind in der Regel nicht) physisch zusammenhängend, auch wenn viel zusammenhängender Arbeitsspeicher verfügbar ist. Aufrufer, die zusammenhängenden Arbeitsspeicher benötigen, sollten MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS anstelle von MM_ALLOCATE_PREFER_CONTIGUOUS angeben. |
| MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS 0x00000020 | Zusammenhängender Arbeitsspeicher ist erforderlich. Ab Windows 7 gibt dieses Flag an, dass die angeforderten Seiten als zusammenhängende Blöcke des physischen Arbeitsspeichers zugeordnet werden müssen. Wenn der SkipBytes-Parameter 0 ist, ist MmAllocatePagesForMdlEx entweder erfolgreich und gibt einen einzelnen zusammenhängenden Block zurück, oder er schlägt fehl und gibt NULL zurück. Es gibt nie eine partielle Zuordnung zurück. Für SkipBytes = 0 erfüllen die zugeordneten Seiten die Adressbereichsanforderungen, die durch die Parameter LowAddress und HighAddress angegeben werden, aber die Seiten unterliegen keinen besonderen Ausrichtungseinschränkungen. Wenn SkipBytes nichtzero ist, muss SkipBytes eine Leistung von zwei und größer oder gleich PAGE_SIZE sein, und der Wert des TotalBytes-Parameters muss ein Vielfaches von SkipBytes sein. In diesem Fall kann die zurückgegebene MDL mehrere Blöcke zusammenhängender Seiten enthalten. Das heißt, jeder Block ist intern zusammenhängend, aber die Blöcke sind nicht notwendigerweise miteinander zusammenhängend. Jeder Block zusammenhängender Seiten ist garantiert genau SkipBytes lang und wird an einer SkipBytes-Grenze ausgerichtet. Partielle Zuordnungen können auftreten, wenn SkipBytes nicht zero ist, aber jeder zusammenhängende Block in einer partiellen Zuordnung garantiert SkipBytes long ist. |
| MM_ALLOCATE_FAST_LARGE_PAGES 0x00000040 | Ab Windows 8 gibt dieses Flag an, dass die Zuordnung aus dem Großen Seitencache des Betriebssystems erfüllt werden muss. Wenn der Cache leer ist, schlägt die Zuordnung fehl. Wenn MM_ALLOCATE_FAST_LARGE_PAGES nicht angegeben ist, verwendet MmAllocatePagesForMdlEx zwischengespeicherte große Seiten, sofern sie verfügbar sind. Wenn der Cache erschöpft ist, versucht MmAllocatePagesForMdlEx , zusätzliche große Seiten zu erstellen, was lange dauern kann. MM_ALLOCATE_FAST_LARGE_PAGES müssen mit dem MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS-Flag verwendet werden. Der SkipBytes-Parameter muss auf ein Vielfaches der großen Seitengröße festgelegt werden. |
| MM_ALLOCATE_AND_HOT_REMOVE 0x00000100 | Ab Windows 10 bewirkt dieses Flag, dass die zugeordneten Seiten aus dem von Windows verwalteten Pool des physischen Arbeitsspeichers entfernt werden. MM_ALLOCATE_AND_HOT_REMOVE können nicht zusammen mit MM_ALLOCATE_FULLY_REQUIRED angegeben werden. Wenn MM_ALLOCATE_AND_HOT_REMOVE angegeben ist, muss der Aufrufer unter IRQL = PASSIVE_LEVEL ausgeführt werden. |
Rückgabewert
MmAllocatePagesForMdlEx gibt eine der folgenden Rückgaben zurück:
| Rückgabecode | Beschreibung |
|---|---|
| MDL-Zeiger | Ein Nicht-NULL-Rückgabewert ist ein Zeiger auf eine MDL, die einen Satz physischer Seiten im angegebenen Adressbereich beschreibt. Wenn die angeforderte Anzahl von Bytes nicht verfügbar ist, beschreibt die MDL so viel physischen Arbeitsspeicher, wie verfügbar ist. |
| NULL | Gibt an, dass in den angegebenen Adressbereichen keine Seiten des physischen Arbeitsspeichers verfügbar sind oder dass nicht genügend Arbeitsspeicherpool für die MDL selbst vorhanden ist. |
Hinweise
Standardmäßig sind die von MmAllocatePagesForMdlEx zurückgegebenen Seiten des physischen Arbeitsspeichers keine zusammenhängenden Seiten. Ab Windows 7 können Aufrufer das Standardverhalten dieser Routine überschreiben, indem sie das MM_ALLOCATE_PREFER_CONTIGUOUS oder MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS Flagbit im Flags-Parameter festlegen.
MmAllocatePagesForMdlEx ist für Kernelmodustreiber konzipiert, die keine entsprechenden virtuellen Adressen benötigen (d.a. sie benötigen physische Seiten und müssen nicht physisch zusammenhängend sein), und für Kernelmodustreiber, die erhebliche Leistungssteigerungen erzielen können, wenn der physische Arbeitsspeicher für ein Gerät in einem bestimmten physischen Adressbereich zugeordnet ist (z. B. eine AGP-Grafik Karte).
Je nachdem, wie viel physischer Arbeitsspeicher derzeit in den angeforderten Bereichen verfügbar ist, gibt MmAllocatePagesForMdlEx möglicherweise eine MDL zurück, die weniger Arbeitsspeicher als angefordert beschreibt. Die Routine kann auch NULL zurückgeben, wenn kein Arbeitsspeicher zugewiesen wurde. Der Aufrufer sollte überprüfen, wie viel Arbeitsspeicher tatsächlich der MDL zugeordnet ist.
Der Aufrufer muss MmFreePagesFromMdl verwenden, um die Speicherseiten freizugeben, die von einer MDL beschrieben werden, die von MmAllocatePagesForMdlEx erstellt wurde. Nach dem Aufruf von MmFreePagesFromMdl muss der Aufrufer auch ExFreePool aufrufen, um den Speicher freizugeben, der für die MDL-Struktur zugewiesen ist.
Standardmäßig füllt MmAllocatePagesForMdlEx die Seiten, die es ordnet, mit Nullen. Der Aufrufer kann das MM_DONT_ZERO_ALLOCATION-Flag angeben, um diese Standardeinstellung zu überschreiben und möglicherweise die Leistung zu verbessern.
Der von MmAllocatePagesForMdlEx zugewiesene Arbeitsspeicher wird nicht initialisiert, wenn Sie das MM_DONT_ZERO_ALLOCATION-Flag angeben. Ein Kernelmodustreiber muss diesen Arbeitsspeicher zuerst null betragen, wenn der Treiber den Speicher für Die Software im Benutzermodus sichtbar macht (um zu vermeiden, dass potenziell privilegierte Inhalte verloren gehen). Weitere Informationen zu diesem Flag finden Sie unter MM_ALLOCATE_XXX.
Die maximale Arbeitsspeichermenge, die MmAllocatePagesForMdlEx in einem einzelnen Aufruf zuweisen kann, ist (4 Gigabyte – PAGE_SIZE). Die Routine kann eine Zuordnungsanforderung für diesen Betrag nur erfüllen, wenn genügend Seiten verfügbar sind.
MmAllocatePagesForMdlEx wird unter IRQL <= APC_LEVEL ausgeführt. Anrufer von MmAllocatePagesForMdlEx dürfen sich an DISPATCH_LEVEL befinden. Sie können jedoch die Leistung des Treibers verbessern, indem Sie unter APC_LEVEL oder darunter aufrufen.
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 | IrqlMmApcLte(wdm) |