MmAllocateMdlForIoSpace-Funktion (wdm.h)

Artikel
02/27/2024

Die MmAllocateMdlForIoSpace-Routine weist eine MDL zu und initialisiert diese MDL, um einen Satz physischer Adressbereiche im E/A-Adressraum zu beschreiben.

Syntax

NTSTATUS MmAllocateMdlForIoSpace(
  [in]  PMM_PHYSICAL_ADDRESS_LIST PhysicalAddressList,
  [in]  SIZE_T                    NumberOfEntries,
  [out] PMDL                      *NewMdl
);

Parameter

[in] PhysicalAddressList

Ein Zeiger auf ein Array von MM_PHYSICAL_ADDRESS_LIST Strukturen, die die physischen Adressbereiche beschreiben, die in die zugeordnete MDL eingeschlossen werden sollen.

[in] NumberOfEntries

Die Anzahl der Elemente im MM_PHYSICAL_ADDRESS_LIST Arrays, auf das von PhysicalAddressList verwiesen wird.

[out] NewMdl

Ein Zeiger auf eine Position, an die die Routine einen Zeiger auf die neu zugewiesene MDL schreibt.

Rückgabewert

MmAllocateMdlForIoSpace gibt bei erfolgreicher Ausführung STATUS_SUCCESS zurück. Mögliche Fehlerrückgabewerte umfassen die folgenden status-Codes.

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER_1	Eine physische Adresse ist nicht an einer Seitengrenze ausgerichtet. oder ein physischer Adressbereich kein Vielfaches der Seitengröße ist; oder ein physischer Adressbereich wird vom Betriebssystem für RAM verwendet und steht nicht als E/A-Speicherplatz zur Verfügung.
STATUS_INSUFFICIENT_RESOURCES	Zum Ausführen des angeforderten Vorgangs stehen nicht genügend Systemressourcen zur Verfügung.

Gehen Sie nicht davon aus, dass die vorherige Liste der Fehlerrückgabecodes vollständig ist. Die Routine gibt möglicherweise Fehlercodes zurück, die nicht in der Liste angezeigt werden.

Hinweise

Diese Routine akzeptiert als Eingabeparameter ein Array von MM_PHYSICAL_ADDRESS_LIST Strukturen, die einen Satz von physischen Adressbereichen im E/A-Adressraum beschreiben, und weist eine MDL zu, die diese Bereiche beschreibt. Aufeinanderfolgende physische Adressbereiche im Array müssen nicht zusammenhängend sein.

Die physischen Adressbereiche im Array PhysicalAddressList müssen die folgenden Bedingungen erfüllen:

Die physische Basisadresse für jeden Bereich muss an einer PAGE_SIZE Grenze im Arbeitsspeicher ausgerichtet sein.
Die Größe jedes Bereichs in Bytes muss ein ganzzahliges Vielfaches von PAGE_SIZE sein.
Alle physischen Adressbereiche müssen sich im Arbeitsspeicher befinden, der für die Verwendung als E/A-Adressraum verfügbar ist. Sie dürfen sich nicht im Arbeitsspeicher befinden, der vom Betriebssystem für RAM verwendet wird.
Die Gesamtgröße aller Bereiche muss kleiner als 4 Gigabyte sein. Insbesondere darf die Gesamtgröße 2^32 bis 1 Bytes nicht überschreiten.

Der Aufrufer ist dafür verantwortlich, die zugewiesene MDL frei zu geben, wenn sie nicht mehr benötigt wird. Rufen Sie zum Freigeben der MDL die IoFreeMdl-Routine auf. Weitere Informationen zu MDLs finden Sie unter Verwenden von MDLs.

Die von MmAllocateMdlForIoSpace erstellte MDL ist nicht dem virtuellen Arbeitsspeicher zugeordnet, kann jedoch einer Routine wie MapTransferEx bereitgestellt werden, um eine DMA-Übertragung in die von der MDL beschriebenen physischen Speicherbereiche zu initiieren. Um diese MDL einem zusammenhängenden Bereich virtueller Adressen zuzuordnen, damit der Prozessor darauf zugreifen kann, rufen Sie die MmMapLockedPagesSpecifyCache-Routine auf.

Nur Bereiche des physischen Adressraums, die nicht vom Betriebssystem für die Verwendung als Arbeitsspeicher reserviert sind, stehen Treibern zur Verwendung als E/A-Adressraum zur Verfügung. Treiber verwenden E/A-Adressraum, um auf speicherbezogene Hardwareressourcen wie Geräteregister zuzugreifen. Wenn ein Treiber gestartet wird, erhält er möglicherweise mindestens einen physischen Adressbereich als übersetzte Hardwareressourcen. Weitere Informationen finden Sie unter Zuordnen Bus-Relative Adressen zu virtuellen Adressen.

In einigen Prozessorarchitekturen, z. B. x86, können Geräte entweder speicherseitig zugeordnet oder Portadressen in einem speziellen E/A-Adressraum zugeordnet werden, der für Geräte reserviert ist und vom Speicheradressraum getrennt ist. Treiber können MmAllocateMdlForIoSpace verwenden, um MDLs nur für Geräte mit Speicherzuordnung zuzuweisen.

Beispiele

Im folgenden Codebeispiel wird gezeigt, wie ein Array von MM_PHYSICAL_ADDRESS_LIST Strukturen erstellt wird, die die physischen Adressbereiche beschreiben, die in die zugeordnete MDL eingeschlossen werden sollen.

extern ULONG64 BasePhysicalAddress;
extern SIZE_T ChunkSize;
extern SIZE_T Stride;

#define ARRAYSIZE(x)  (sizeof(x)/sizeof((x)[0]))
 
NTSTATUS Status;
PMDL Mdl;
MM_PHYSICAL_ADDRESS_LIST AddressList[3];
 
AddressList[0].PhysicalAddress.QuadPart = BasePhysicalAddress;
AddressList[0].NumberOfBytes = ChunkSize;
 
BasePhysicalAddress += Stride;
 
AddressList[1].PhysicalAddress.QuadPart = BasePhysicalAddress;
AddressList[1].NumberOfBytes = ChunkSize;
 
BasePhysicalAddress += Stride;
 
AddressList[2].PhysicalAddress.QuadPart = BasePhysicalAddress;
AddressList[2].NumberOfBytes = ChunkSize;
 
Status = MmAllocateMdlForIoSpace (AddressList, ARRAYSIZE(AddressList), &Mdl);

In diesem Beispiel wird die physische Startadresse von der BasePhysicalAddress Variablen angegeben. Die Anzahl der Bytes in jedem physischen Adressbereich wird von der ChunkSize Variablen angegeben. Der Byteoffset vom Anfang eines physischen Bereichs bis zum Anfang des nächsten wird von der Stride Variablen angegeben. BasePhysicalAddress muss an einer Seitengrenze im Arbeitsspeicher ausgerichtet sein, und ChunkSizeStride muss ein Vielfaches der Seitengröße sein.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.
Zielplattform	Universell
Header	wdm.h (einschließen von Wdm.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL