IoBuildPartialMdl-Funktion (wdm.h)

Artikel
08/08/2023

Die IoBuildPartialMdl-Routine erstellt eine neue Speicherdeskriptorliste (Memory Descriptor List, MDL), die einen Teil eines Puffers darstellt, der durch eine vorhandene MDL beschrieben wird.

Syntax

void IoBuildPartialMdl(
  [in]      PMDL  SourceMdl,
  [in, out] PMDL  TargetMdl,
  [in]      PVOID VirtualAddress,
  [in]      ULONG Length
);

Parameter

[in] SourceMdl

Ein Zeiger auf eine MDL, der den ursprünglichen Puffer beschreibt, dem ein Unterbereich zugeordnet werden soll.

[in, out] TargetMdl

Ein Zeiger auf eine vom Aufrufer zugewiesene MDL. Diese MDL muss groß genug sein, um die Seiten im Unterbereich zu beschreiben, die durch VirtualAddress und Length angegeben werden.

[in] VirtualAddress

Ein Zeiger auf die virtuelle Basisadresse für den Unterbereich, der von TargetMdl beschrieben werden soll.

[in] Length

Gibt die Länge in Bytes an, die vom TargetMdl zugeordnet werden soll. Dieser Wert muss in Kombination mit VirtualAddress einen Puffer angeben, der ein richtiger Unterbereich des Puffers ist, der von SourceMdl beschrieben wird. Wenn Length 0 ist, beginnt der zu zuordnende Unterbereich bei VirtualAddress und umfasst den verbleibenden Bereich, der von SourceMdl beschrieben wird.

Rückgabewert

Keine

Bemerkungen

Diese Routine erstellt eine Ziel-MDL, die einen Teilbereich des Puffers beschreibt, der von der Quell-MDL beschrieben wird. Dieser Unterbereich wird durch die Parameter VirtualAddress und Length angegeben. Die Parameter SourceMdl und TargetMdl verweisen auf die Quell-MDL und die Ziel-MDL.

Ein Treiber kann IoBuildPartialMdl verwenden, um eine große Übertragungsanforderung in kleinere Übertragungsanforderungen aufzuteilen. Die physischen Seiten, die die Quell-MDL beschreibt, müssen gesperrt werden, bevor der Treiber IoBuildPartialMdl aufruft. In der Regel beschreibt die Quell-MDL einen Puffer im Benutzeradressraum, und der Treiber ruft die MmProbeAndLockPages-Routine auf, um die Seiten in diesem Puffer zu sperren. Der Treiber kann jedoch die Quell-MDL aus nicht aus dem Auslagerspeicher erstellen, indem er die Routine MmBuildMdlForNonPagedPool, MmAllocatePagesForMdlEx oder MmAllocatePagesForMdl aufruft .

Beim Erstellen einer partiellen MDL:

Wenn die ursprüngliche MDL bereits im Systemraum zugeordnet war, gibt die partielle MDL diese Zuordnung frei, und es ist nicht erforderlich, sie erneut zu zuordnen.
Wenn die ursprüngliche MDL nicht im Systemraum zugeordnet wurde, ist die partielle MDL auch nicht. Wenn Sie eine Systemmodusadresse benötigen, rufen Sie MmGetSystemAddressForMdlSafe für die partielle MDL auf.
Wenn Sie nicht wissen, welche der oben genannten Punkte zutrifft, ist es sicher , MmGetSystemAddressForMdlSafe unabhängig davon aufzurufen. Wenn eine partielle MDL aus einer Quell-MDL erstellt wird, die bereits dem Systemadressraum zugeordnet ist, verwendet MmGetSystemAddressForMdlSafe die vorhandene Quellzuordnung. Andernfalls erstellt MmGetSystemAddressForMdlSafe eine neue Zuordnung.

Um zu verhindern, dass diese neue Zuordnung durchgesickert wird, müssen Treiber MmPrepareMdlForReuse aufrufen, bevor sie eine partielle MDL wiederverwenden. Darüber hinaus gibt die IoFreeMdl-Routine die Systemadressraumzuordnung für eine partielle MDL frei, wenn eine solche Zuordnung vorhanden ist.

Weitere Informationen zu MDLs finden Sie unter Verwenden von MDLs.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 2000.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	MdlAfterReqCompletedIntIoctlA(kmdf), MdlAfterReqCompletedIoctlA(kmdf), MdlAfterReqCompletedReadA(kmdf), MdlAfterReqCompletedWriteA(kmdf)